org.geotoolkit.referencing.operation.builder
Class GridToEnvelopeMapper

Object
  GridToEnvelopeMapper

public class GridToEnvelopeMapper
extends Object

A helper class for building n-dimensional affine transform mapping grid envelopes to georeferenced envelopes. The affine transform will be computed automatically from the information specified by the setGridExtent(GridEnvelope) and setEnvelope(Envelope) 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 extent) 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 CRS has the same characteristics than the BufferedImage 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 unnatural, but it reflects the fact that row values are increasing down in an BufferedImage CRS.

Since:

2.3

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

coverage/geotk-coverage (download)

View source code for this class

Field Summary

static int	REVERSE_AXIS A bit mask for the reverseAxis property.
static int	SWAP_XY A bit mask for the swapXY property.

Constructor Summary

GridToEnvelopeMapper()
Creates a new instance of GridToEnvelopeMapper.

GridToEnvelopeMapper(GridEnvelope gridExtent, Envelope envelope)
Creates a new instance for the specified grid envelope and georeferenced envelope.

Method Summary

AffineTransform	createAffineTransform() Returns the Grid to Envelope (or grid to CRS) transform as a two-dimensional affine transform.
MathTransform	createTransform() Creates a Grid to Envelope (or grid to CRS) transform using the information provided by setter methods.
Envelope	getEnvelope() Returns the georeferenced envelope.
GridEnvelope	getGridExtent() Returns the The extent of grid coordinates in a grid coverage.
GridEnvelope	getGridRange() Deprecated. Renamed getGridExtent().
PixelInCell	getPixelAnchor() Returns whatever the grid coordinates map 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) Sets all properties designed by the specified bit mask as automatic.
void	setEnvelope(double x, double y, double width, double height) Sets the envelope as a two-dimensional rectangle.
void	setEnvelope(Envelope envelope) Sets the georeferenced envelope.
void	setEnvelope(Rectangle2D envelope) Sets the envelope as a two-dimensional rectangle.
void	setGridExtent(GridEnvelope extent) Sets the The extent of grid coordinates in a grid coverage.
void	setGridExtent(int x, int y, int width, int height) Sets the grid envelope as a two-dimensional rectangle.
void	setGridExtent(Rectangle extent) Sets the grid envelope as a two-dimensional rectangle.
void	setGridRange(GridEnvelope extent) Deprecated. Renamed setGridExtent(GridEnvelope).
void	setGridRange(int x, int y, int width, int height) Deprecated. Renamed setGridExtent(GridEnvelope).
void	setGridRange(Rectangle extent) Deprecated. Renamed setGridExtent(GridEnvelope).
void	setPixelAnchor(PixelInCell anchor) Sets whatever the grid coordinates map pixel center or pixel corner.
void	setReverseAxis(boolean[] reverse) Sets 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 gridExtent,
                            Envelope envelope)
                     throws MismatchedDimensionException

Creates a new instance for the specified grid envelope and georeferenced envelope.

Parameters:

gridExtent - The extent of grid coordinates in a grid coverage.

envelope - The corresponding domain in user coordinate. This envelope must contains entirely all pixels, i.e. the envelope upper left corner must coincide with the upper left corner of the first pixel and the envelope lower right corner must coincide with the lower right corner of the last pixel.

Throws:

MismatchedDimensionException - if the two envelopes don't have consistent dimensions.

Method Detail

getPixelAnchor

public PixelInCell getPixelAnchor()

Returns whatever the grid coordinates map 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 coordinates map pixel center or corner.

Since:

2.5

setPixelAnchor

public void setPixelAnchor(PixelInCell anchor)

Sets whatever the grid coordinates map pixel center or pixel corner. The former is OGC convention while the later is Java2D/JAI convention. The default is cell center (OGC convention).

Parameters:

anchor - Whatever the grid coordinates map pixel center or corner.

Since:

2.5

getGridExtent

public GridEnvelope getGridExtent()
                           throws IllegalStateException

Returns the The extent of grid coordinates in a grid coverage.

Returns:

The The extent of grid coordinates in a grid coverage.

Throws:

IllegalStateException - if the grid envelope has not yet been defined.

getGridRange

@Deprecated
public GridEnvelope getGridRange()
                          throws IllegalStateException

Deprecated. Renamed getGridExtent().

Throws:

IllegalStateException

setGridExtent

public void setGridExtent(GridEnvelope extent)

Sets the The extent of grid coordinates in a grid coverage.

Parameters:

extent - The new grid envelope.

Since:

3.20 (derived from 2.3)

setGridRange

@Deprecated
public void setGridRange(GridEnvelope extent)

Deprecated. Renamed setGridExtent(GridEnvelope).

setGridExtent

public void setGridExtent(Rectangle extent)

Sets the grid envelope as a two-dimensional rectangle. This convenience method creates a GridEnvelope2D from the given rectangle and delegates to the setGridExtent(GridEnvelope) method.

Parameters:

extent - The new grid envelope.

Since:

3.20 (derived from 3.15)

setGridRange

@Deprecated
public void setGridRange(Rectangle extent)

Deprecated. Renamed setGridExtent(GridEnvelope).

setGridExtent

public void setGridExtent(int x,
                          int y,
                          int width,
                          int height)

Sets the grid envelope as a two-dimensional rectangle. This convenience method creates a GridEnvelope2D from the given rectangle and delegates to the setGridExtent(GridEnvelope) method.

Parameters:

x - The minimal x ordinate.

y - The minimal y ordinate.

width - The number of valid ordinates along the x axis.

height - The number of valid ordinates along the y axis.

Since:

3.20 (derived from 3.15)

setGridRange

@Deprecated
public void setGridRange(int x,
                                    int y,
                                    int width,
                                    int height)

Deprecated. Renamed setGridExtent(GridEnvelope).

getEnvelope

public Envelope getEnvelope()
                     throws IllegalStateException

Returns the georeferenced envelope. For performance reason, this method does 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 georeferenced 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.

setEnvelope

public void setEnvelope(Rectangle2D envelope)

Sets the envelope as a two-dimensional rectangle. This convenience method creates an Envelope2D from the given rectangle and delegates to the setEnvelope(Envelope) method.

Parameters:

envelope - The new envelope.

Since:

3.15

setEnvelope

public void setEnvelope(double x,
                        double y,
                        double width,
                        double height)

Sets the envelope as a two-dimensional rectangle. This convenience method creates an Envelope2D from the given rectangle and delegates to the setEnvelope(Envelope) method.

Parameters:

x - The x minimal value.

y - The y minimal value.

width - The envelope width.

height - The envelope height.

Since:

3.15

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 envelope matches exactly axis order in the genreferenced 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 makes the following assumptions:

• Axis should be reverted if needed in order to have the most commonly used direction for increasing positive values (North, East, Up, Future).
• 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)

Sets 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)

Sets 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 Grid to Envelope (or grid to CRS) transform using the information provided by setter methods. The default implementation returns an instance of LinearTransform, but subclasses could create more complex transforms.

Returns:

The grid to CRS transform.

Throws:

IllegalStateException - if the grid envelope or the georeferenced envelope were not set.

createAffineTransform

public AffineTransform createAffineTransform()
                                      throws IllegalStateException

Returns the Grid to Envelope (or grid to CRS) transform as a two-dimensional affine transform.

Returns:

The grid to CRS transform as a two-dimensional affine transform.

Throws:

IllegalStateException - if the math transform is not of the appropriate type.