org.apache.sis.referencing.operation.builder

## Class LocalizationGridBuilder

- Object
- - TransformBuilder
  - - LocalizationGridBuilder

-     public class LocalizationGridBuilder
      extends TransformBuilder

  Creates an "almost linear" transform mapping the given source points to the given target points. The transform is backed by a grid of localization, a two-dimensional array of coordinate points. Grid size is `width` × `height` and input coordinates are (i,j) index in the grid, where i must be in the [0…`width`-1] range and j in the [0…`height`-1] range inclusive. Output coordinates are the values stored in the grid of localization at the specified index. After a `LocalizationGridBuilder` instance has been fully populated (i.e. real world coordinates have been specified for all grid cells), a transformation from grid coordinates to "real world" coordinates can be obtained with the `create(MathTransformFactory)` method. If this transform is close enough to an affine transform, then an instance of `LinearTransform` is returned. Otherwise, a transform backed by the localization grid is returned.

  This builder performs two steps:

  1. Compute a linear approximation of the transformation using `LinearTransformBuilder`.
  2. Compute `DatumShiftGrid` with the residuals.
  3. Create a `InterpolatedTransform` with the above shift grid.
  Since:
    0.8
  See Also:
    `InterpolatedTransform`, `LinearTransform`, `DatumShiftGrid`

  Defined in the `sis-referencing` module

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `LocalizationGridBuilder(int width, int height)` Creates a new, initially empty, builder for a localization grid of the given size.
    `LocalizationGridBuilder(Vector sourceX, Vector sourceY)` Creates a new, initially empty, builder for a localization grid of a size inferred from the given points.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `MathTransform` | `create(MathTransformFactory factory)` Creates a transform from the source points to the target points.
    `double[]` | `getControlPoint(int gridX, int gridY)` Returns a single target coordinate for the given source coordinate, or `null` if none.
    `double` | `getDesiredPrecision()` Returns the desired precision of inverse transformations, in units of source coordinates.
    `LinearTransform` | `getSourceToGrid()` Returns the current relationship between "real-world" source coordinates and grid coordinates.
    `void` | `setControlPoint(int gridX, int gridY, double... target)` Sets a single matching control point pair.
    `void` | `setDesiredPrecision(double precision)` Sets the desired precision of inverse transformations, in units of source coordinates.
    `void` | `setSourceToGrid(LinearTransform sourceToGrid)` Defines relationship between "real-world" source coordinates and grid coordinates.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### LocalizationGridBuilder

          public LocalizationGridBuilder(int width,
                                         int height)

      Creates a new, initially empty, builder for a localization grid of the given size.
      Parameters:
        `width` - the number of columns in the grid of target positions.
        `height` - the number of rows in the grid of target positions.

    - #### LocalizationGridBuilder

          public LocalizationGridBuilder(Vector sourceX,
                                         Vector sourceY)

      Creates a new, initially empty, builder for a localization grid of a size inferred from the given points. This constructor uses the given vectors for computing a grid size and the following initial conversion:

      > (`sourceX`, `sourceY`) → (`gridX`, `gridY`)

      Above conversion can be obtained by `getSourceToGrid()`.

      Values in the given vectors should be integers, but this constructor is tolerant to non-integer values if they have a constant offset (typically 0.5) relative to integer values. The two vectors do not need to have the same length (i.e. `sourceX[i]` are not necessarily related to `sourceY[i]`).

      Parameters:
        `sourceX` - all possible x inputs before conversion to grid coordinates.
        `sourceY` - all possible y inputs before conversion to grid coordinates.
      Throws:
        `ArithmeticException` - if this constructor can not infer a reasonable grid size from the given vectors.

  - ### Method Detail

    - #### setDesiredPrecision

          public void setDesiredPrecision(double precision)

      Sets the desired precision of inverse transformations, in units of source coordinates. If a conversion from "real world" to grid coordinates has been specified, then the given precision is in "real world" units. Otherwise the precision is in units of grid cells.
      Note: there is no method for setting the desired target precision because forward transformations precision (not to be confused with accuracy) are limited only by rounding errors. Of course the accuracy of both forward and inverse transformations still limited by the accuracy of given control points and the grid resolution.
      Parameters:
        `precision` - desired precision of the results of inverse transformations.
      See Also:
        `DatumShiftGrid​.getCellPrecision()`

    - #### getDesiredPrecision

          public double getDesiredPrecision()

      Returns the desired precision of inverse transformations, in units of source coordinates. This is the precision sets by the last call to `setDesiredPrecision(double)`.
      Returns:
        desired precision of the results of inverse transformations.

    - #### setSourceToGrid

          public void setSourceToGrid(LinearTransform sourceToGrid)

      Defines relationship between "real-world" source coordinates and grid coordinates. The given transform is usually two-dimensional, in which case conversions from (x,y) source coordinates to (`gridX`, `gridY`) indices can be done with the following formulas:
      - gridX = (x - x₀) / Δx
      - gridY = (y - y₀) / Δy
      where:
      - (x₀, y₀) is the coordinate of the center of the cell at grid index (0,0).
      - Δx and Δy are the distances between two cells on the x and y axes respectively, in the same unit of measurement than the one documented in the `setDesiredPrecision(double)` method.
      The `coordinateToGrid` transform for the above formulas can be represented by the following matrix:

          ┌                      ┐
          │ 1/Δx      0   -x₀/Δx │
          │    0   1/Δy   -y₀/Δy │
          │    0      0        1 │
          └                      ┘

      If this method is never invoked, then the default conversion is identity. If a desired precision has been specified before this method call, it is caller's responsibility to convert that value to new source units if needed.
      Parameters:
        `sourceToGrid` - conversion from the "real world" source coordinates to grid indices including fractional parts.
      See Also:
        `DatumShiftGrid​.getCoordinateToGrid()`

    - #### getSourceToGrid

          public LinearTransform getSourceToGrid()

      Returns the current relationship between "real-world" source coordinates and grid coordinates. This is the value set by the last call to `setSourceToGrid(LinearTransform)`. If that setter method has never been invoked, then this is an automatically computed transform if the grid coordinates have been specified to the constructor, or the identity transform otherwise.
      Returns:
        the current relationship between "real-world" source coordinates and grid coordinates.

    - #### setControlPoint

          public void setControlPoint(int gridX,
                                      int gridY,
                                      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.

      If a source to grid conversion exists, it shall have been applied by the caller for computing the (`gridX`, `gridY`) coordinates given to this method.

      Parameters:
        `gridX` - the column index in the grid where to store the given target position.
        `gridY` - the row index in the grid where to store the given target position.
        `target` - the target coordinates, assumed uncertain.
      Throws:
        `IllegalArgumentException` - if the `x` or `y` ordinate value is out of grid range.
        `MismatchedDimensionException` - if the target position does not have the expected number of dimensions.

    - #### getControlPoint

          public double[] getControlPoint(int gridX,
                                          int gridY)

      Returns a single target coordinate for the given source coordinate, or `null` if none.
      Parameters:
        `gridX` - the column index in the grid where to read the target position.
        `gridY` - the row index in the grid where to read the target position.
      Returns:
        the target coordinates associated to the given source, or `null` if none.
      Throws:
        `IllegalArgumentException` - if the `x` or `y` ordinate value is out of grid range.

    - #### create

          public MathTransform create(MathTransformFactory factory)
                               throws FactoryException

      Creates a transform from the source points to the target points. This method assumes that source points are precise and all uncertainty is in the target points. If this transform is close enough to an affine transform, then an instance of `LinearTransform` is returned.
      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 transform from source to target points.
      Throws:
        `FactoryException` - if the transform can not be created, for example because the target points have not be specified.

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