Package org.apache.sis.image

# Interface Interpolation

public interface Interpolation
Algorithm for image interpolation (resampling). Interpolations are performed by sampling on a regular grid of pixels using a local neighborhood. The sampling is performed by the `ResampledImage` class, which gives the sample values to the `interpolate(…)` method of this interpolation.

All methods in this interface shall be safe for concurrent use in multi-threading context. For example interpolations may be executed in a different thread for each tile in an image.

This interface is designed for interpolations in a two-dimensional space only.

Since:
  1.1

Defined in the `sis-feature` module

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Interpolation`
  `BILINEAR`
  A bilinear interpolation using 2×2 pixels.
  `static final Interpolation`
  `LANCZOS`
  Lanczos interpolation for photographic images.
  `static final Interpolation`
  `NEAREST`
  A nearest-neighbor interpolation using 1×1 pixel.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Dimension`
  `getSupportSize()`
  Returns the size of the area over which the resampling function needs to provide values.
  `void`
  `interpolate(DoubleBuffer source, int numBands, double xfrac, double yfrac, double[] writeTo, int writeToOffset)`
  Interpolates sample values for all bands using the given pixel values in local neighborhood.

- ## Field Details

  - ### NEAREST

    static final Interpolation NEAREST
    A nearest-neighbor interpolation using 1×1 pixel.

  - ### BILINEAR

    static final Interpolation BILINEAR
    A bilinear interpolation using 2×2 pixels. If the interpolation result is NaN, this method fallbacks on nearest-neighbor.

  - ### LANCZOS

    static final Interpolation LANCZOS
    Lanczos interpolation for photographic images. This interpolation is not recommended for images that may contain NaN values.
    See Also:
      - Lanczos resampling on Wikipedia

- ## Method Details

  - ### getSupportSize

    Dimension getSupportSize()
    Returns the size of the area over which the resampling function needs to provide values. Common values are:

    Common support sizes
    Interpolation | Width | Height
    --- | --- | ---
    Nearest-neighbor | 1 | 1
    Bilinear | 2 | 2
    Bicubic | 4 | 4
    Lanczos | 4 | 4

    Returns:
      number of sample values required for interpolations.

  - ### interpolate

    void interpolate(DoubleBuffer source, int numBands, double xfrac, double yfrac, double[] writeTo, int writeToOffset)
    Interpolates sample values for all bands using the given pixel values in local neighborhood. The given `source` is a buffer with the number of elements shown below, where support width and support height are given by `getSupportSize()`:

    > (number of bands) × (support width) × (support height)

    Values in `source` buffer are always given with band index varying fastest, then column index, then row index. Columns are traversed from left to right and rows are traversed from top to bottom (`SequenceType​.LINEAR` iteration order).

    The interpolation point is in the middle. For example if the support size is 4×4 pixels, then the interpolation point is the dot below and the fractional coordinates are relative to the horizontal and vertical lines drawn below. This figure is for an image with only one band, otherwise all indices between brackets would need to be multiplied by `numBands`.

    >     s[0]   s[1]   s[2]   s[3]

    >     s[4]   s[5]───s[6]   s[7]  ← yfrac = 0
    >             │   ●              ← yfrac given
    >     s[8]   s[9]   s[10]  s[11] ← yfrac = 1

    >     s[12]  s[13]  s[14]  s[15]
    >                 ↑
    >               xfrac

    On output, this method shall write the interpolation results as `numBands` consecutive values in the supplied `writeTo` array, starting at `writeToOffset` index. This method should not modify the buffer position (use `DoubleBuffer​.mark()` and `reset()` if needed).
    Parameters:
      `source` - pixel values from the source image to use for interpolation.
      `numBands` - number of bands. This is the number of values to put in the `writeTo` array.
      `xfrac` - the X subsample position, usually (but not always) in the range [0 … 1).
      `yfrac` - the Y subsample position, usually (but not always) in the range [0 … 1).
      `writeTo` - the array where this method shall write interpolated values.
      `writeToOffset` - index of the first value to put in the `writeTo` array.