Module org.apache.sis.feature

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 Pixel­Orientation or Pixel­In­Cell. The translation are returned by a call to one of the following static methods:

• get­Pixel­Translation(Pixel­Orientation) for the two-dimensional case.
• get­Pixel­Translation(Pixel­In­Cell) for the n-dimensional case.

This class provides also a few translate(…) convenience methods, which apply the translation on a given Math­Transform instance.

Example

In the following code snippet, grid­To­CRS is an Affine­Transform 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:

    public AffineTransform getGridToPixelCorner() {
        AffineTransform  gridToCRS = ...;
        PixelOrientation current   = PixelOrientation.CENTER;
        PixelOrientation desired   = PixelOrientation.UPPER_LEFT;

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

Since:

1.0

See Also:

• Pixel­In­Cell
• Pixel­Orientation
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
final double	dx	The translation among the x axis relative to pixel center.
final double	dy	The translation among the y axis relative to pixel center.
final Pixel­Orientation	orientation	The pixel orientation for this translation.

Method Summary

Modifier and Type	Method	Description
static Pixel­Orientation	get­Pixel­Orientation(Pixel­In­Cell anchor)	Returns the pixel orientation which is equivalent to the given Pixel­In­Cell code.
static Pixel­Translation	get­Pixel­Translation(Pixel­Orientation anchor)	Returns the specified position relative to the pixel center.
static double	get­Pixel­Translation(Pixel­In­Cell anchor)	Returns the position relative to the cell center.
String	to­String()	Returns a string representation of this pixel translation.
static Math­Transform	translate(Math­Transform grid­To­CRS, Pixel­Orientation current, Pixel­Orientation desired, int x­Dimension, int y­Dimension)	Converts a math transform from a "pixel orientation" convention to another "pixel orientation" convention.
static Math­Transform	translate(Math­Transform grid­To­CRS, Pixel­In­Cell current, Pixel­In­Cell 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, get­Class, hash­Code, notify, notify­All, wait, wait, wait

Field Details

orientation

public final PixelOrientation orientation

The pixel orientation for this translation. Most common values are Pixel­Orientation.UPPER_LEFT and Pixel­Orientation.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 Details

getPixelOrientation

public static PixelOrientation getPixelOrientation(PixelInCell anchor)

Returns the pixel orientation which is equivalent to the given Pixel­In­Cell 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 Pixel­In­Cell code, or null.

Returns:

the corresponding pixel orientation, or null if the argument was null.

Throws:

Illegal­Argument­Exception - 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:

Illegal­Argument­Exception - 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:

Illegal­Argument­Exception - 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.

If the given grid­To­CRS is null, then this method ignores all other arguments and returns null. Otherwise current and desired arguments must be non-null.

Example

If a given grid­To­CRS transform was mapping the cell corner to "real world" coordinates, then a call to translate(grid­To­CRS, 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 grid­To­CRS 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.

Parameters:

grid­To­CRS - a math transform from pixel coordinates to any CRS, or null.

current - the pixel orientation of the given grid­To­CRS transform.

desired - the pixel orientation of the desired transform.

Returns:

the translation from current to desired, or null if grid­To­CRS was null.

Throws:

Illegal­Argument­Exception - 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.

If the given grid­To­CRS is null, then this method ignores all other arguments and returns null. Otherwise current and desired arguments must be non-null.

Example

If a given grid­To­CRS transform was mapping the upper-left corner to "real world" coordinates, then a call to translate(grid­To­CRS, UPPER_LEFT, CENTER, 0, 1) will return a new transform translating grid coordinates by +0.5 before to apply the given grid­To­CRS transform. See example in above translate method for more details.

Parameters:

grid­To­CRS - a math transform from pixel coordinates to any CRS, or null.

current - the pixel orientation of the given grid­To­CRS transform.

desired - the pixel orientation of the desired transform.

x­Dimension - the dimension of x coordinates (pixel columns). Often 0.

y­Dimension - the dimension of y coordinates (pixel rows). Often 1.

Returns:

the translation from current to desired, or null if grid­To­CRS was null.

Throws:

Illegal­Argument­Exception - if current or desired is not a known code list value.

toString

public String toString()

Returns a string representation of this pixel translation.

Overrides:

to­String in class Object