Module org.apache.sis.feature
Package org.apache.sis.coverage

# Class CoverageCombiner

Object
CoverageCombiner

public class CoverageCombiner extends Object
Combines an arbitrary number of coverages into a single one. The combined coverages may use different coordinate systems. The workflow is as below:

1. Creates a `CoverageCombiner` with the destination coverage where to write.
2. Configure with methods such as `setInterpolation(…)`.
3. Invoke `acceptAll(…)` methods for each list of coverages to combine.
4. Get the combined coverage with `result()`.

Coverage domains can have any number of dimensions. Coverages are combined in the order they are specified. For each coverage, sample dimensions are combined in the order they appear, regardless their names. For each sample dimension, values are converted to the unit of measurement of the destination coverage.

## Limitations

The current implementation has the following limitations. Those restrictions may be resolved progressively in future Apache SIS versions.

- Supports only `GridCoverage` instances, not yet more generic coverages.
- No interpolation except in the two dimensions having the largest size (usually the 2 first). For all other dimensions, data are taken from the nearest neighbor two-dimensional slice.
- No expansion of the destination coverage for accommodating data of source coverages that are outside the destination coverage bounds.

Since:
  1.4
See Also:
  - `ImageCombiner`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CoverageCombiner(GridCoverage destination)`
  Creates a coverage combiner which will write in the given coverage.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `acceptAll(GridCoverage... sources)`
  Writes the given coverages on top of the destination coverage.
  `Interpolation`
  `getInterpolation()`
  Returns the interpolation method to use during resample operations.
  `GridCoverage`
  `result()`
  Returns the combination of destination coverage with all coverages specified to `CoverageCombiner` methods.
  `void`
  `setInterpolation(Interpolation method)`
  Sets the interpolation method to use during resample operations.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### CoverageCombiner

    public CoverageCombiner(GridCoverage destination)
    Creates a coverage combiner which will write in the given coverage. The coverage is not cleared: cells that are not overwritten by calls to the `accept(…)` method will be left unchanged.
    Parameters:
      `destination` - the destination coverage where to combine source coverages.
    Throws:
      `CannotEvaluateException` - if the coverage does not have at least 2 dimensions.

- ## Method Details

  - ### getInterpolation

    public Interpolation getInterpolation()
    Returns the interpolation method to use during resample operations.

    #### Limitations

    In current version, the interpolation is applied only in the `xdim` and `ydim` dimensions specified at construction time. For all other dimensions, nearest neighbor interpolation is applied.
    Returns:
      interpolation method to use during resample operations.

  - ### setInterpolation

    public void setInterpolation(Interpolation method)
    Sets the interpolation method to use during resample operations.

    #### Limitations

    In current version, the interpolation is applied only in the `xdim` and `ydim` dimensions specified at construction time. For all other dimensions, nearest neighbor interpolation is applied.
    Parameters:
      `method` - interpolation method to use during resample operations.

  - ### acceptAll

    public boolean acceptAll(GridCoverage... sources) throws TransformException, IncommensurableException
    Writes the given coverages on top of the destination coverage. The given coverages are resampled to the grid geometry of the destination coverage. Coverages that do not intercept with the destination coverage are silently ignored.

    #### Performance note

    If there is many coverages to write, they should be specified in a single call to `acceptAll(…)` instead of invoking this method multiple times. Bulk operations can reduce the number of calls to `GridCoverage​.render(GridExtent)`.
    Parameters:
      `sources` - the coverages to write on top of destination coverage.
    Returns:
      `true` on success, or `false` if at least one slice in the destination coverage is not writable.
    Throws:
      `TransformException` - if the coordinates of a given coverage cannot be transformed to the coordinates of destination coverage.
      `IncommensurableException` - if the unit of measurement of at least one source sample dimension is not convertible to the unit of measurement of the corresponding target sample dimension.

  - ### result

    public GridCoverage result()
    Returns the combination of destination coverage with all coverages specified to `CoverageCombiner` methods. This may be the destination coverage specified at construction time, but may also be a larger coverage if the destination has been dynamically expanded for accommodating larger sources.

    Note: dynamic expansion is not yet implemented in current version. If a future version implements it, we shall guarantee that the coordinate of each cell is unchanged (i.e. the grid extent `minX` and `minY` may become negative, but the cell identified by coordinates (0,0) for instance will stay the same cell.)

    Returns:
      the combination of destination coverage with all source coverages.