Class PixelTranslation

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.coverage.grid.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: 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:
Since:
1.0
Version:
1.0
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final double
    The translation among the x axis relative to pixel center.
    final double
    The translation among the y axis relative to pixel center.
    final org.opengis.metadata.spatial.PixelOrientation
    The pixel orientation for this translation.
    private static final Map<org.opengis.metadata.spatial.PixelOrientation,PixelTranslation>
    The offset for various pixel orientations.
    private static final long
    For cross-version compatibility.
    private static final org.opengis.referencing.operation.MathTransform[]
    Math transforms created by translate(MathTransform, PixelInCell, PixelInCell) for dimensions 1 to 6.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    PixelTranslation(org.opengis.metadata.spatial.PixelOrientation orientation, double dx, double dy)
    Creates a new pixel translation.
  • Method Summary

    Modifier and Type
    Method
    Description
    private static void
    add(org.opengis.metadata.spatial.PixelOrientation orientation, double dx, double dy)
    For ORIENTATIONS construction only.
    static org.opengis.metadata.spatial.PixelOrientation
    getPixelOrientation(org.opengis.referencing.datum.PixelInCell anchor)
    Returns the pixel orientation which is equivalent to the given PixelInCell code.
    getPixelTranslation(org.opengis.metadata.spatial.PixelOrientation anchor)
    Returns the specified position relative to the pixel center.
    static double
    getPixelTranslation(org.opengis.referencing.datum.PixelInCell anchor)
    Returns the position relative to the cell center.
    illegalDimension(String name, Object dimension)
    Formats an exception for an illegal dimension.
    Returns a string representation of this pixel translation.
    static org.opengis.referencing.operation.MathTransform
    translate(org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.metadata.spatial.PixelOrientation current, org.opengis.metadata.spatial.PixelOrientation desired, int xDimension, int yDimension)
    Converts a math transform from a "pixel orientation" convention to another "pixel orientation" convention.
    static org.opengis.referencing.operation.MathTransform
    translate(org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.referencing.datum.PixelInCell current, org.opengis.referencing.datum.PixelInCell desired)
    Converts a math transform from a "pixel in cell" convention to another "pixel in cell" convention.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • translations

      private static final org.opengis.referencing.operation.MathTransform[] translations
      Math transforms created by translate(MathTransform, PixelInCell, PixelInCell) for dimensions 1 to 6. Each element in this array will be created when first needed. Even indices are translations by -0.5 while odd indices are translations by +0.5.
    • orientation

      public final org.opengis.metadata.spatial.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 +½.
    • ORIENTATIONS

      private static final Map<org.opengis.metadata.spatial.PixelOrientation,PixelTranslation> ORIENTATIONS
      The offset for various pixel orientations. Keys must be upper-case names.
  • Constructor Details

    • PixelTranslation

      private PixelTranslation(org.opengis.metadata.spatial.PixelOrientation orientation, double dx, double dy)
      Creates a new pixel translation.
  • Method Details

    • add

      private static void add(org.opengis.metadata.spatial.PixelOrientation orientation, double dx, double dy)
      For ORIENTATIONS construction only.
    • getPixelOrientation

      public static org.opengis.metadata.spatial.PixelOrientation getPixelOrientation(org.opengis.referencing.datum.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 cellPixel orientation
      CELL_CENTERCENTER
      CELL_CORNERUPPER_LEFT
      nullnull
      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(org.opengis.referencing.datum.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 celloffset
      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(org.opengis.metadata.spatial.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 org.opengis.referencing.operation.MathTransform translate(org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.referencing.datum.PixelInCell current, org.opengis.referencing.datum.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 centercell 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 org.opengis.referencing.operation.MathTransform translate(org.opengis.referencing.operation.MathTransform gridToCRS, org.opengis.metadata.spatial.PixelOrientation current, org.opengis.metadata.spatial.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.
    • illegalDimension

      private static IllegalArgumentException illegalDimension(String name, Object dimension)
      Formats an exception for an illegal dimension.
    • toString

      public String toString()
      Returns a string representation of this pixel translation.
      Overrides:
      toString in class Object