Package org.apache.sis.coverage.grid

# Class DomainLinearizer

Object
DomainLinearizer

public class DomainLinearizer extends Object
Method for replacing a non-linear "grid to CRS" conversion by a linear conversion (affine transform). The `GridGeometry` class allows non-linear "grid to CRS" conversions, but some `GridGeometry` usages are restricted to linear (affine) conversions. The `DomainLinearizer` class encapsulates the method used for replacing non-linear conversions by a linear approximation.

The same instance can be reused by invoking `apply(…)` methods for many `GridCoverage` or `GridGeometry` instances.

## Limitations

Current implementation is designed for two-dimensional grid geometries. Support for higher dimensions is not guaranteed.

Since:
  1.1
See Also:
  - `LinearTransformBuilder​.approximate(MathTransform, Envelope)`

Defined in the `sis-feature` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DomainLinearizer()`
  Creates a new linearizer.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GridCoverage`
  `apply(GridCoverage coverage)`
  Returns a grid coverage with a linear approximation of the grid to CRS conversion.
  `GridGeometry`
  `apply(GridGeometry gg)`
  Creates a grid geometry with a linear approximation of the grid to CRS conversion.
  `boolean`
  `getGridStartsAtZero()`
  Returns whether `GridExtent` should have their lower grid coordinates set to zero.
  `double`
  `getScaleFactor()`
  Returns the scale factor applied on coordinates in all dimensions.
  `void`
  `setGridStartsAtZero(boolean force)`
  Sets whether `GridExtent` should have their lower grid coordinates set to zero.
  `void`
  `setScaleFactor(double factor)`
  Sets the scale factor to apply on coordinates in all dimensions.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### DomainLinearizer

    public DomainLinearizer()
    Creates a new linearizer.

- ## Method Details

  - ### getGridStartsAtZero

    public boolean getGridStartsAtZero()
    Returns whether `GridExtent` should have their lower grid coordinates set to zero. If `true`, then `DomainLinearizer` will opportunistically apply translation on the "grid to CRS" conversion in such a way that `GridExtent​.getLow()` is 0 for all dimensions.
    Returns:
      whether to force lower grid coordinates to (0,0,…).
    See Also:
      - `GridExtent​.startsAtZero()`

  - ### setGridStartsAtZero

    public void setGridStartsAtZero(boolean force)
    Sets whether `GridExtent` should have their lower grid coordinates set to zero. The default value is `false`.
    Parameters:
      `force` - whether to force lower grid coordinates to (0,0,…).

  - ### getScaleFactor

    public double getScaleFactor()
    Returns the scale factor applied on coordinates in all dimensions.
    Returns:
      scale factor applied on coordinates in all dimensions, or 1 if none.

  - ### setScaleFactor

    public void setScaleFactor(double factor)
    Sets the scale factor to apply on coordinates in all dimensions. Must be a value greater than zero. The default value is 1.
    Parameters:
      `factor` - scale factor applied on coordinates in all dimensions, or 1 if none.

  - ### apply

    public GridCoverage apply(GridCoverage coverage) throws TransformException
    Returns a grid coverage with a linear approximation of the grid to CRS conversion. The linear approximation is computed by `apply(GridGeometry)`. If the grid to CRS conversion of the given coverage is already linear, then this method returns `coverage`.
    Parameters:
      `coverage` - the grid coverage in which to make the grid to CRS conversion linear.
    Returns:
      a grid coverage with a linear approximation of the grid to CRS conversion.
    Throws:
      `TransformException` - if some cell coordinates can not be computed.

  - ### apply

    public GridGeometry apply(GridGeometry gg) throws TransformException
    Creates a grid geometry with a linear approximation of the grid to CRS conversion. The approximation is computed by Least Mean Squares method: the affine transform coefficients are chosen in way making the average value of (position − linear approximation of position)² as small as possible for all cells in given grid geometry. If the grid to CRS conversion of the given grid geometry is already linear, then this method returns `gg`.
    Parameters:
      `gg` - the grid geometry in which to make the grid to CRS conversion linear.
    Returns:
      a grid geometry with a linear approximation of the grid to CRS conversion.
    Throws:
      `TransformException` - if some cell coordinates can not be computed.