org.geotoolkit.referencing.operation.transform
Class GridTransform

Object
  FormattableObject
      AbstractMathTransform
          GridTransform

All Implemented Interfaces:

Serializable, Formattable, Parameterized, LenientComparable, MathTransform

Direct Known Subclasses:

GridTransform2D

@Immutable
public class GridTransform
extends AbstractMathTransform
implements Serializable

Transforms a set of coordinate points using bilinear interpolation in a grid.

Input and output coordinates
First, "real world" input coordinates (x, y) are optionally converted to grid coordinates (xi, yi), which are zero-based index in the two-dimensional grid. This conversion is applied only if a "real world" envelope was given to the constructor, otherwise the input coordinates are assumed to be directly grid coordinates.

Note: This real world to grid transform is affine, but is still performed internally by this class in a simplified form (no rotation or axis swapping) rather than delegated to an AffineTransform instance because this class needs the original coordinates if the grid values are offset to be added, as in NADCON grids.

Output coordinates are the values stored in the grid at the specified grid coordinate. If the grid ordinates are non-integer values, then output coordinates are interpolated using a bilinear interpolation. If the grid ordinates are outside the grid domain ([0 … width-2] × [0 … height-2] where width and height are the number of columns and rows in the grid), then output coordinates are extrapolated.

In the case of a LOCALIZATION grid, we are done. But in the case of OFFSET, NADCON or NTv2 grids, the above coordinates are added to the input coordinates in order to get the final output coordinates.

Invertibility
By default GridTransforms are not invertible. However some subclasses like GridTransform2D and the one created by LocalizationGrid provide conditional support for inverse transforms.

Since:

3.00

Version:

3.18

Author:

Rémi Eve (IRD), Martin Desruisseaux (IRD, Geomatys), Simon Reynard (Geomatys)

See Also:

Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Nested Class Summary

Nested classes/interfaces inherited from class AbstractMathTransform

AbstractMathTransform.Inverse

Field Summary

protected DataBuffer	grid The grid of values.
protected int	height Number of rows in the grid.
protected int	width Number of columns in the grid.

Fields inherited from class FormattableObject

EPSG, GEOTIFF, INTERNAL, OGC, SINGLE_LINE

Constructor Summary

protected

GridTransform(GridType type, DataBuffer grid, Dimension size, Rectangle2D area) Constructs a grid using the specified data.

Method Summary

protected int	computeHashCode() Computes a hash value for this transform.
static GridTransform	create(GridType type, DataBuffer grid, Dimension size, Rectangle2D area) Constructs a grid using the specified data.
static GridTransform	create(int width, int height, double[]... data) Constructs a localization grid using the specified data.
static GridTransform	create(int width, int height, float[]... data) Constructs a localization grid using the specified data.
Matrix	derivative(DirectPosition point) Gets an estimation of the derivative of this transform at a point.
boolean	equals(Object object, ComparisonMode mode) Compares this transform with the specified object for equality.
int	getSourceDimensions() Returns the dimension of input points, which is 2.
int	getTargetDimensions() Returns the dimension of output points.
boolean	isIdentity() Returns false since this transform is not the identity one.
protected void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff) Transforms a source coordinate into target coordinate.
void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Transforms a source coordinate into target coordinate.
void	transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) Transforms a source coordinate into target coordinate.
void	transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Transforms a source coordinate into target coordinate.
void	transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) Transforms a source coordinate into target coordinate.

Methods inherited from class AbstractMathTransform

createTransformedShape, derivative, ensureNonNull, equals, formatWKT, getName, getParameterDescriptors, getParameterValues, hashCode, inverse, rollLongitude, transform, transform

Methods inherited from class FormattableObject

getDefaultIndentation, print, setDefaultIndentation, toString, toWKT, toWKT, toWKT

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface MathTransform

toWKT

Field Detail

width

protected final int width

Number of columns in the grid.

height

protected final int height

Number of rows in the grid.

grid

protected final transient DataBuffer grid

The grid of values. The size is equal to the product of the width and height. The number of banks determines the target dimension, which is typically 2. The buffer type is typically DataBufferFloat or DataBufferDouble, but is not restricted to.

When a transform method is invoked, a target value is interpolated for every banks in the data buffer. Values in each data buffer bank are stored in row-major order.

Constructor Detail

GridTransform

protected GridTransform(GridType type,
                        DataBuffer grid,
                        Dimension size,
                        Rectangle2D area)

Constructs a grid using the specified data.

Parameters:

type - Whatever the grid values are directly the target coordinates or offsets to apply on source coordinates.

grid - The grid of values. It must complies with the conditions documented in the grid field.

size - Number of columns (width) and rows (height) in the grid.

area - Grid envelope in "real world" coordinates, or null if none. The minimal (x,y) coordinate will maps the (0,0) grid coordinate, and the maximal (x,y) coordinate will maps the (width, height) grid coordinate.

Method Detail

create

public static GridTransform create(int width,
                                   int height,
                                   float[]... data)

Constructs a localization grid using the specified data. This convenience method creates the intermediate DataBufferFloat object from the supplied data assuming that the first valid values is located at index 0. If this is not the case, user can create a DataBufferFloat object directly in order to gain more control.

Parameters:

width - Number of columns in the grid.

height - Number of rows in the grid.

data - Data stored in row-major order, one array for each target dimension.

Returns:

The math transform backed by the given grid.

create

public static GridTransform create(int width,
                                   int height,
                                   double[]... data)

Constructs a localization grid using the specified data. This convenience method creates the intermediate DataBufferDouble object from the supplied data assuming that the first valid values is located at index 0. If this is not the case, user can create a DataBufferDouble object directly in order to gain more control.

Parameters:

width - Number of columns in the grid.

height - Number of rows in the grid.

data - Data stored in row-major order, one array for each target dimension.

Returns:

The math transform backed by the given grid.

create

public static GridTransform create(GridType type,
                                   DataBuffer grid,
                                   Dimension size,
                                   Rectangle2D area)

Constructs a grid using the specified data.

Parameters:

type - Whatever the grid values are directly the target coordinates or offsets to apply on source coordinates.

grid - The grid of values. It must complies with the conditions documented in the grid field.

size - Number of columns (width) and rows (height) in the grid.

area - Grid envelope in "real world" coordinates, or null if none. The minimal (x,y) coordinate will maps the (0,0) grid coordinate, and the maximal (x,y) coordinate will maps the (size.width, size.height) grid coordinate.

Returns:

The math transform backed by the given grid.

getSourceDimensions

public final int getSourceDimensions()

Returns the dimension of input points, which is 2.

Specified by:

getSourceDimensions in interface MathTransform

Specified by:

getSourceDimensions in class AbstractMathTransform

getTargetDimensions

public final int getTargetDimensions()

Returns the dimension of output points. This is the number of banks in the underlying grid.

Specified by:

getTargetDimensions in interface MathTransform

Specified by:

getTargetDimensions in class AbstractMathTransform

isIdentity

public boolean isIdentity()

Returns false since this transform is not the identity one.

Specified by:

isIdentity in interface MathTransform

Overrides:

isIdentity in class AbstractMathTransform

derivative

public Matrix derivative(DirectPosition point)

Gets an estimation of the derivative of this transform at a point.

Specified by:

derivative in interface MathTransform

Overrides:

derivative in class AbstractMathTransform

Parameters:

point - The coordinate point where to evaluate the derivative.

Returns:

The derivative at the specified point (never null).

transform

protected void transform(double[] srcPts,
                         int srcOff,
                         double[] dstPts,
                         int dstOff)

Transforms a source coordinate into target coordinate. The transformation will involve bilinear interpolations if the source ordinates are not integer values.

Specified by:

transform in class AbstractMathTransform

Parameters:

srcPts - The source coordinate.

srcOff - Index of the first valid ordinate in the srcPts array.

dstPts - Where to store the target coordinate.

dstOff - Index where to store the first ordinate.

transform

public void transform(double[] srcPts,
                      int srcOff,
                      double[] dstPts,
                      int dstOff,
                      int numPts)

Transforms a source coordinate into target coordinate. The transformation will involve bilinear interpolations if the source ordinates are not integer values.

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The source coordinates.

srcOff - Index of the first valid ordinate in the srcPts array.

dstPts - Where to store the target coordinates.

dstOff - Index where to store the first ordinate.

numPts - The number of point objects to be transformed.

transform

public void transform(float[] srcPts,
                      int srcOff,
                      float[] dstPts,
                      int dstOff,
                      int numPts)

Transforms a source coordinate into target coordinate. The transformation will involve bilinear interpolations if the source ordinates are not integer values.

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The source coordinates.

srcOff - Index of the first valid ordinate in the srcPts array.

dstPts - Where to store the target coordinates.

dstOff - Index where to store the first ordinate.

numPts - The number of point objects to be transformed.

transform

public void transform(double[] srcPts,
                      int srcOff,
                      float[] dstPts,
                      int dstOff,
                      int numPts)

Transforms a source coordinate into target coordinate. The transformation will involve bilinear interpolations if the source ordinates are not integer values.

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The source coordinates.

srcOff - Index of the first valid ordinate in the srcPts array.

dstPts - Where to store the target coordinates.

dstOff - Index where to store the first ordinate.

numPts - The number of point objects to be transformed.

transform

public void transform(float[] srcPts,
                      int srcOff,
                      double[] dstPts,
                      int dstOff,
                      int numPts)

Transforms a source coordinate into target coordinate. The transformation will involve bilinear interpolations if the source ordinates are not integer values.

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The source coordinates.

srcOff - Index of the first valid ordinate in the srcPts array.

dstPts - Where to store the target coordinates.

dstOff - Index where to store the first ordinate.

numPts - The number of point objects to be transformed.

computeHashCode

protected int computeHashCode()

Computes a hash value for this transform. This method is invoked by AbstractMathTransform.hashCode() when first needed.

Overrides:

computeHashCode in class AbstractMathTransform

Returns:

The hash code value. This value may change between different execution of the Geotk library.

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compares this transform with the specified object for equality. This method returns true if the two objects are of the same class and have the same width, height, target dimension and the same values in all valid grid cells. Note that the grids are not required to be of the same type (TYPE_FLOAT, TYPE_DOUBLE, etc.) if the values casted to the double type are equal.

Specified by:

equals in interface LenientComparable

Overrides:

equals in class AbstractMathTransform

Parameters:

object - The object to compare with this transform.

mode - The strictness level of the comparison. Default to STRICT.

Returns:

true if the given object is a transform of the same class and if, given identical source position, the transformed position would be the equals.