GridToEnvelopeMapper (Geotools modules 28-SNAPSHOT API)

Object
- GridToEnvelopeMapper

```
public class GridToEnvelopeMapper
extends Object
```
A helper class for building n-dimensional affine transform mapping grid ranges to envelopes. The affine transform will be computed automatically from the information specified by the setGridRange and setEnvelope methods, which are mandatory. All other setter methods are optional hints about the affine transform to be created. This builder is convenient when the following conditions are meet:
- Pixels coordinates (usually (x,y) integer values inside the rectangle specified by the grid range) are expressed in some coordinate reference system known at compile time. This is often the case. For example the CRS attached to BufferedImage has always (column, row) axis, with the origin (0,0) in the upper left corner, and row values increasing down.
- "Real world" coordinates (inside the envelope) are expressed in arbitrary horizontal coordinate reference system. Axis directions may be (North, West), or (East, North), etc..
In such case (and assuming that the image's CRS has the same characteristics than the BufferedImage's CRS described above):
- swapXY shall be set to true if the "real world" axis order is (North, East) instead of (East, North). This axis swapping is necessary for mapping the (column, row) axis order associated to the image CRS.
- In addition, the "real world" axis directions shall be reversed (by invoking reverseAxis(dimension)) if their direction is WEST (x axis) or NORTH (y axis), in order to get them oriented toward the EAST or SOUTH direction respectively. The later may seems unatural, but it reflects the fact that row values are increasing down in an BufferedImage's CRS.
Since:

2.3

Author:

Martin Desruisseaux (IRD)

Field Summary

Fields
Modifier and Type Field and Description

static int REVERSE_AXIS
A bit mask for the reverseAxis property.

static int SWAP_XY
A bit mask for the swapXY property.

Fields
Modifier and Type	Field and Description
`static int`	`REVERSE_AXIS` A bit mask for the `reverseAxis` property.
`static int`	`SWAP_XY` A bit mask for the `swapXY` property.

Constructor Summary

Constructors
Constructor and Description
`GridToEnvelopeMapper()` Creates a new instance of `GridToEnvelopeMapper`.
`GridToEnvelopeMapper(GridEnvelope gridRange, Envelope userRange)` Creates a new instance for the specified grid range and envelope.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`AffineTransform`	`createAffineTransform()` Returns the math transform as a two-dimensional affine transform.
`MathTransform`	`createTransform()` Creates a math transform using the information provided by setter methods.
`Envelope`	`getEnvelope()` Returns the envelope.
`GridEnvelope`	`getGridRange()` Returns the grid range.
`PixelInCell`	`getPixelAnchor()` Returns whatever the grid range maps pixel center or pixel corner.
`boolean[]`	`getReverseAxis()` Returns which (if any) axis in user space (not grid space) should have their direction reversed.
`boolean`	`getSwapXY()` Returns `true` if the two first axis should be interchanged.
`boolean`	`isAutomatic(int mask)` Returns `true` if all properties designed by the specified bit mask will be computed automatically.
`void`	`reverseAxis(int dimension)` Reverses a single axis in user space.
`void`	`setAutomatic(int mask)` Set all properties designed by the specified bit mask as automatic.
`void`	`setEnvelope(Envelope envelope)` Sets the envelope.
`void`	`setGridRange(GridEnvelope gridRange)` Sets the grid range.
`void`	`setPixelAnchor(PixelInCell anchor)` Sets whatever the grid range maps pixel center or pixel corner.
`void`	`setReverseAxis(boolean[] reverse)` Set which (if any) axis in user space (not grid space) should have their direction reversed.
`void`	`setSwapXY(boolean swapXY)` Tells if the two first axis should be interchanged.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SWAP_XY
```
public static final int SWAP_XY
```
    A bit mask for the swapXY property.
    
    See Also:
    
    isAutomatic(int), setAutomatic(int), Constant Field Values
  - REVERSE_AXIS
```
public static final int REVERSE_AXIS
```
    A bit mask for the reverseAxis property.
    
    See Also:
    
    isAutomatic(int), setAutomatic(int), Constant Field Values
- Constructor Detail
  - GridToEnvelopeMapper
```
public GridToEnvelopeMapper()
```
    Creates a new instance of GridToEnvelopeMapper.
  - GridToEnvelopeMapper
```
public GridToEnvelopeMapper(GridEnvelope gridRange,
                            Envelope userRange)
                     throws MismatchedDimensionException
```
    Creates a new instance for the specified grid range and envelope.
    
    Parameters:
    
    gridRange - The valid coordinate range of a grid coverage.
    
    userRange - The corresponding coordinate range in user coordinate. This envelope must contains entirely all pixels, i.e. the envelope's upper left corner must coincide with the upper left corner of the first pixel and the envelope's lower right corner must coincide with the lower right corner of the last pixel.
    
    Throws:
    
    MismatchedDimensionException - if the grid range and the envelope doesn't have consistent dimensions.
- Method Detail
  - getPixelAnchor
```
public PixelInCell getPixelAnchor()
```
    Returns whatever the grid range maps pixel center or pixel corner. The former is OGC convention while the later is Java2D/JAI convention. The default is cell center (OGC convention).
    
    Returns:
    
    Whatever the grid range maps pixel center or corner.
    
    Since:
    
    2.5
  - setPixelAnchor
```
public void setPixelAnchor(PixelInCell anchor)
```
    Sets whatever the grid range maps pixel center or pixel corner. The former is OGC convention while the later is Java2D/JAI convention.
    
    Parameters:
    
    anchor - Whatever the grid range maps pixel center or corner.
    
    Since:
    
    2.5
  - getGridRange
```
public GridEnvelope getGridRange()
                          throws IllegalStateException
```
    Returns the grid range.
    
    Returns:
    
    The grid range.
    
    Throws:
    
    IllegalStateException - if the grid range has not yet been defined.
  - setGridRange
```
public void setGridRange(GridEnvelope gridRange)
```
    Sets the grid range.
    
    Parameters:
    
    gridRange - The new grid range.
  - getEnvelope
```
public Envelope getEnvelope()
                     throws IllegalStateException
```
    Returns the envelope. For performance reason, this method do not clone the envelope. So the returned object should not be modified.
    
    Returns:
    
    The envelope.
    
    Throws:
    
    IllegalStateException - if the envelope has not yet been defined.
  - setEnvelope
```
public void setEnvelope(Envelope envelope)
```
    Sets the envelope. This method do not clone the specified envelope, so it should not be modified after this method has been invoked.
    
    Parameters:
    
    envelope - The new envelope.
  - getSwapXY
```
public boolean getSwapXY()
```
    Returns true if the two first axis should be interchanged. If isAutomatic(SWAP_XY) returns true (which is the default), then this method make the following assumptions:
    - Axis order in the grid range matches exactly axis order in the envelope, except for the special case described in the next point. In other words, if axis order in the underlying image is (column, row) (which is the case for a majority of images), then the envelope should probably have a (longitude, latitude) or (easting, northing) axis order.
    - An exception to the above rule applies for CRS using exactly the following axis order: (NORTH|SOUTH, EAST|WEST). An example of such CRS is EPSG:4326. In this particular case, this method will returns true, thus suggesting to interchange the (y,x) axis for such CRS.
    Returns:
    
    true if the two first axis should be interchanged.
  - setSwapXY
```
public void setSwapXY(boolean swapXY)
```
    Tells if the two first axis should be interchanged. Invoking this method force isAutomatic(SWAP_XY) to false.
    
    Parameters:
    
    swapXY - true if the two first axis should be interchanged.
  - getReverseAxis
```
public boolean[] getReverseAxis()
```
    Returns which (if any) axis in user space (not grid space) should have their direction reversed. If isAutomatic(REVERSE_AXIS) returns true (which is the default), then this method make the following assumptions:
    - Axis should be reverted if needed in order to point toward their "absolute" direction.
    - An exception to the above rule is the second axis in grid space, which is assumed to be the y axis on output device (usually the screen). This axis is reversed again in order to match the bottom direction often used with such devices.
    Returns:
    
    The reversal state of each axis, or null if unspecified.
  - setReverseAxis
```
public void setReverseAxis(boolean[] reverse)
```
    Set which (if any) axis in user space (not grid space) should have their direction reversed. Invoking this method force isAutomatic(REVERSE_AXIS) to false.
    
    Parameters:
    
    reverse - The reversal state of each axis. A null value means to reverse no axis.
  - reverseAxis
```
public void reverseAxis(int dimension)
```
    Reverses a single axis in user space. Invoking this methods n time is equivalent to creating a boolean reverse array of the appropriate length, setting reverse[dimension] = true for the n axis to be reversed, and invoke setReverseAxis(reverse).
    
    Parameters:
    
    dimension - The index of the axis to reverse.
  - isAutomatic
```
public boolean isAutomatic(int mask)
```
    Returns true if all properties designed by the specified bit mask will be computed automatically.
    
    Parameters:
    
    mask - Any combination of REVERSE_AXIS or SWAP_XY.
    
    Returns:
    
    true if all properties given by the mask will be computed automatically.
  - setAutomatic
```
public void setAutomatic(int mask)
```
    Set all properties designed by the specified bit mask as automatic. Their value will be computed automatically by the corresponding methods (e.g. getReverseAxis(), getSwapXY()). By default, all properties are automatic.
    
    Parameters:
    
    mask - Any combination of REVERSE_AXIS or SWAP_XY.
  - createTransform
```
public MathTransform createTransform()
                              throws IllegalStateException
```
    Creates a math transform using the information provided by setter methods.
    
    Returns:
    
    The math transform.
    
    Throws:
    
    IllegalStateException - if the grid range or the envelope were not set.
  - createAffineTransform
```
public AffineTransform createAffineTransform()
                                      throws IllegalStateException
```
    Returns the math transform as a two-dimensional affine transform.
    
    Returns:
    
    The math transform as a two-dimensional affine transform.
    
    Throws:
    
    IllegalStateException - if the math transform is not of the appropriate type.

Class GridToEnvelopeMapper

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Detail

SWAP_XY

REVERSE_AXIS

Constructor Detail

GridToEnvelopeMapper

GridToEnvelopeMapper

Method Detail

getPixelAnchor

setPixelAnchor

getGridRange

setGridRange

getEnvelope

setEnvelope

getSwapXY

setSwapXY

getReverseAxis

setReverseAxis

reverseAxis

isAutomatic

setAutomatic

createTransform

createAffineTransform