Package org.apache.sis.image

# Class ImageCombiner

Object
ImageCombiner

All Implemented Interfaces:
  `Consumer<RenderedImage>`

public class ImageCombiner extends Object implements Consumer<RenderedImage>
Combines an arbitrary amount of images into a single one. The combined mages may use different coordinate systems if a resampling operation is specified. The workflow is as below:

1. Creates an `ImageCombiner` with the destination image where to write.
2. Configure with methods such as `setInterpolation(…)`.
3. Invoke `accept(…)` or `resample(…)` methods for each image to combine.
4. Get the combined image with `result()`.

Images are combined in the order they are specified. If the same pixel is written by many images, then the final value is the pixel of the last image specified. In current implementation, the last pixel values win even if those pixels are transparent (i.e. `ImageCombiner` does not yet handle alpha values).

Since:
  1.1

Defined in the `sis-feature` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ImageCombiner(WritableRenderedImage destination)`
  Creates an image combiner which will write in the given image.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `accept(RenderedImage source)`
  Writes the given image on top of destination image.
  `Interpolation`
  `getInterpolation()`
  Returns the interpolation method to use during resample operations.
  `Quantity<?>[]`
  `getPositionalAccuracyHints()`
  Returns hints about the desired positional accuracy, in "real world" units or in pixel units.
  `void`
  `resample(RenderedImage source, Rectangle bounds, MathTransform toSource)`
  Combines the result of resampling the given image.
  `RenderedImage`
  `result()`
  Returns the combination of destination image with all images specified to `ImageCombiner` methods.
  `void`
  `setInterpolation(Interpolation method)`
  Sets the interpolation method to use during resample operations.
  `void`
  `setPositionalAccuracyHints(Quantity<?>... hints)`
  Sets hints about desired positional accuracy, in "real world" units or in pixel units.

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Consumer

  `andThen`

- ## Constructor Details

  - ### ImageCombiner

    public ImageCombiner(WritableRenderedImage destination)
    Creates an image combiner which will write in the given image. That image is not cleared; pixels that are not overwritten by another image given to `ImageCombiner` methods will be left unchanged.
    Parameters:
      `destination` - the image where to combine images.

- ## Method Details

  - ### getInterpolation

    public Interpolation getInterpolation()
    Returns the interpolation method to use during resample operations.
    Returns:
      interpolation method to use during resample operations.
    See Also:
      - `resample(RenderedImage, Rectangle, MathTransform)`

  - ### setInterpolation

    public void setInterpolation(Interpolation method)
    Sets the interpolation method to use during resample operations.
    Parameters:
      `method` - interpolation method to use during resample operations.
    See Also:
      - `resample(RenderedImage, Rectangle, MathTransform)`

  - ### getPositionalAccuracyHints

    public Quantity<?>[] getPositionalAccuracyHints()
    Returns hints about the desired positional accuracy, in "real world" units or in pixel units. If the returned array is non-empty and contains accuracies large enough, `ImageCombiner` may use some slightly faster algorithms at the expense of accuracy.
    Returns:
      desired accuracy in no particular order, or an empty array if none.
    See Also:
      - `ImageProcessor​.getPositionalAccuracyHints()`

  - ### setPositionalAccuracyHints

    public void setPositionalAccuracyHints(Quantity<?>... hints)
    Sets hints about desired positional accuracy, in "real world" units or in pixel units. Accuracy can be specified in real world units such as metres or in pixel units, which are converted to real world units depending on image resolution. If more than one value is applicable to a dimension (after unit conversion if needed), the smallest value is taken.
    Parameters:
      `hints` - desired accuracy in no particular order, or a `null` array if none. Null elements in the array are ignored.
    See Also:
      - `ImageProcessor​.setPositionalAccuracyHints(Quantity...)`

  - ### accept

    public void accept(RenderedImage source)
    Writes the given image on top of destination image. The given source image shall use the same pixel coordinate system than the destination image (but not necessarily the same tile indices). For every (x,y) pixel coordinates in the destination image:
    - If (x,y) are valid `source` pixel coordinates, then the source pixel values overwrite the destination pixel values.
    - Otherwise the destination pixel is left unchanged.
    Note that source pixels overwrite destination pixels even if they are transparent (i.e. `ImageCombiner` does not yet handle alpha values).
    Specified by:
      `accept` in interface `Consumer<RenderedImage>`
    Parameters:
      `source` - the image to write on top of destination image.

  - ### resample

    public void resample(RenderedImage source, Rectangle bounds, MathTransform toSource)
    Combines the result of resampling the given image. The resampling operation is defined by a potentially non-linear transform from the destination image to the specified source image. That transform should map pixel centers.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Interpolation method (nearest neighbor, bilinear, etc).
    - Positional accuracy hints for enabling faster resampling at the cost of lower precision.
    Contrarily to `ImageProcessor`, this method does not use fill values. Destination pixels that can not be mapped to source pixels are left unchanged.
    Parameters:
      `source` - the image to be resampled.
      `bounds` - domain of pixel coordinates in the destination image, or `null` for the whole image.
      `toSource` - conversion of pixel coordinates from destination image to `source` image.
    See Also:
      - `ImageProcessor​.resample(RenderedImage, Rectangle, MathTransform)`

  - ### result

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

    Note: dynamic expansion is not yet implemented in current version.

    Returns:
      the combination of destination image with all source images.