Package org.apache.sis.coverage.grid

## Class PixelTranslation

- Object
- - Static
  - - PixelTranslation

- All Implemented Interfaces:
    `Serializable`

      public final class PixelTranslation
      extends Static
      implements Serializable

  The translation to apply for different values of `PixelOrientation` or `PixelInCell`. The translation are returned by a call to one of the following static methods:
  - `getPixelTranslation(PixelOrientation)` for the two-dimensional case.
  - `getPixelTranslation(PixelInCell)` for the n-dimensional case.
  This class provides also a few `translate(…)` convenience methods, which apply the translation on a given `MathTransform` instance.
  Example: if the following code snippet, `gridToCRS` is an `AffineTransform` from grid cell coordinates (typically pixel coordinates) to some arbitrary CRS coordinates. In this example, the transform maps pixels center, while the upper left corner is desired. This code will switch the affine transform from the pixel center to upper left corner convention:

  >     final AffineTransform  gridToCRS = ...;
  >     final PixelOrientation current   = PixelOrientation.CENTER;
  >     final PixelOrientation desired   = PixelOrientation.UPPER_LEFT;

  >     // Switch the transform from 'current' to 'desired' convention.
  >     final PixelTranslation source = getPixelTranslation(current);
  >     final PixelTranslation target = getPixelTranslation(desired);
  >     gridToCRS.translate(target.dx - source.dx,
  >                         target.dy - source.dy);

  Since:
    1.0
  See Also:
    `PixelInCell`, `PixelOrientation`, Serialized Form

  Defined in the `sis-feature` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `double` | `dx` | The translation among the x axis relative to pixel center.
    `double` | `dy` | The translation among the y axis relative to pixel center.
    `PixelOrientation` | `orientation` | The pixel orientation for this translation.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static PixelOrientation` | `getPixelOrientation​(PixelInCell anchor)` | Returns the pixel orientation which is equivalent to the given `PixelInCell` code.
    `static PixelTranslation` | `getPixelTranslation​(PixelOrientation anchor)` | Returns the specified position relative to the pixel center.
    `static double` | `getPixelTranslation​(PixelInCell anchor)` | Returns the position relative to the cell center.
    `String` | `toString()` | Returns a string representation of this pixel translation.
    `static MathTransform` | `translate​(MathTransform gridToCRS, PixelOrientation current, PixelOrientation desired, int xDimension, int yDimension)` | Converts a math transform from a "pixel orientation" convention to another "pixel orientation" convention.
    `static MathTransform` | `translate​(MathTransform gridToCRS, PixelInCell current, PixelInCell desired)` | Converts a math transform from a "pixel in cell" convention to another "pixel in cell" convention.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### orientation

          public final PixelOrientation orientation

      The pixel orientation for this translation. Most common values are `PixelOrientation​.UPPER_LEFT` and `PixelOrientation​.CENTER`.

    - #### dx

          public final double dx

      The translation among the x axis relative to pixel center. The value is typically −½, 0 or +½.

    - #### dy

          public final double dy

      The translation among the y axis relative to pixel center. The value is typically −½, 0 or +½.

  - ### Method Detail

    - #### getPixelOrientation

          public static PixelOrientation getPixelOrientation​(PixelInCell anchor)

      Returns the pixel orientation which is equivalent to the given `PixelInCell` code. This equivalence can be used for converting n-dimensional parameters to the more specific two-dimensional case. This method implements the following mapping:

      Pixel orientation equivalences
      Pixel in cell | Pixel orientation
      --- | ---
      `CELL_CENTER` | `CENTER`
      `CELL_CORNER` | `UPPER_LEFT`
      `null` | `null`

      Parameters:
        `anchor` - the `PixelInCell` code, or `null`.
      Returns:
        the corresponding pixel orientation, or `null` if the argument was null.
      Throws:
        `IllegalArgumentException` - if the given `anchor` is not a known code list value.

    - #### getPixelTranslation

          public static double getPixelTranslation​(PixelInCell anchor)

      Returns the position relative to the cell center. This method is typically used for n-dimensional grids, where the number of dimension is unknown. The translation is determined from the following table, with the same value applied to all dimensions:

      Translations
      Pixel in cell | offset
      --- | ---
      `CELL_CENTER` | `0.0`
      `CELL_CORNER` | `-0.5`

      Parameters:
        `anchor` - the "pixel in cell" value.
      Returns:
        the translation for the given "pixel in cell" value.
      Throws:
        `IllegalArgumentException` - if the given `anchor` is not a known code list value.

    - #### getPixelTranslation

          public static PixelTranslation getPixelTranslation​(PixelOrientation anchor)

      Returns the specified position relative to the pixel center. This method can be used for grid restricted to 2 dimensions. The translation vector is determined from the following table:

      Translations
      Pixel orientation | dx | dy
      --- | --- | ---
      `CENTER` | `0.0` | `0.0`
      `UPPER_LEFT` | `-0.5` | `-0.5`
      `UPPER_RIGHT` | `+0.5` | `-0.5`
      `LOWER_LEFT` | `-0.5` | `+0.5`
      `LOWER_RIGHT` | `+0.5` | `+0.5`

      Parameters:
        `anchor` - the pixel orientation.
      Returns:
        the position relative to the pixel center.
      Throws:
        `IllegalArgumentException` - if the given `anchor` is not a known code list value.

    - #### translate

          public static MathTransform translate​(MathTransform gridToCRS,
                                                PixelInCell current,
                                                PixelInCell desired)

      Converts a math transform from a "pixel in cell" convention to another "pixel in cell" convention. This method concatenates −½, 0 or +½ translations on all dimensions before the given transform. If the two given conventions are the same, then this method returns the given transform unchanged.
      Example: if a given `gridToCRS` transform was mapping the cell corner to "real world" coordinates, then a call to `translate(gridToCRS, `CELL_CORNER`, `CELL_CENTER`)` will return a new transform performing the following steps: first convert grid coordinates from cell center convention (`desired`) to cell corner convention (`current`), then concatenate the given `gridToCRS` transform which was designed for the cell corner convention. The above-cited cell center → cell corner conversion is done by translating the grid coordinates by +½, because the grid coordinates (0,0) relative to cell center is (½,½) relative to cell corner.
      If the given `gridToCRS` is null, then this method ignores all other arguments and returns `null`. Otherwise `current` and `desired` arguments must be non-null.
      Parameters:
        `gridToCRS` - a math transform from pixel coordinates to any CRS, or `null`.
        `current` - the pixel orientation of the given `gridToCRS` transform.
        `desired` - the pixel orientation of the desired transform.
      Returns:
        the translation from `current` to `desired`, or `null` if `gridToCRS` was null.
      Throws:
        `IllegalArgumentException` - if `current` or `desired` is not a known code list value.

    - #### translate

          public static MathTransform translate​(MathTransform gridToCRS,
                                                PixelOrientation current,
                                                PixelOrientation desired,
                                                int xDimension,
                                                int yDimension)

      Converts a math transform from a "pixel orientation" convention to another "pixel orientation" convention. This method concatenates −½, 0 or +½ translations on two dimensions before the given transform. The given transform can have any number of input and output dimensions, but only two of them will be converted.
      Example: if a given `gridToCRS` transform was mapping the upper-left corner to "real world" coordinates, then a call to `translate(gridToCRS, `UPPER_LEFT`, `CENTER`, 0, 1)` will return a new transform translating grid coordinates by +0.5 before to apply the given `gridToCRS` transform. See example in above `translate` method for more details.
      If the given `gridToCRS` is null, then this method ignores all other arguments and returns `null`. Otherwise `current` and `desired` arguments must be non-null.
      Parameters:
        `gridToCRS` - a math transform from pixel coordinates to any CRS, or `null`.
        `current` - the pixel orientation of the given `gridToCRS` transform.
        `desired` - the pixel orientation of the desired transform.
        `xDimension` - the dimension of x coordinates (pixel columns). Often 0.
        `yDimension` - the dimension of y coordinates (pixel rows). Often 1.
      Returns:
        the translation from `current` to `desired`, or `null` if `gridToCRS` was null.
      Throws:
        `IllegalArgumentException` - if `current` or `desired` is not a known code list value.

    - #### toString

          public String toString()

      Returns a string representation of this pixel translation.
      Overrides:
        `toString` in class `Object`