org.geotoolkit.referencing.operation.transform
Class ProjectiveTransform

Object
  FormattableObject
      AbstractMathTransform
          ProjectiveTransform

All Implemented Interfaces:

Serializable, Formattable, LinearTransform, Parameterized, LenientComparable, MathTransform

Direct Known Subclasses:

GeocentricAffineTransform

@Immutable
public class ProjectiveTransform
extends AbstractMathTransform
implements LinearTransform, Serializable

A usually affine, or otherwise a projective transform. A projective transform is capable of mapping an arbitrary quadrilateral into another arbitrary quadrilateral, while preserving the straightness of lines. In the special case where the transform is affine, the parallelism of lines in the source is preserved in the output.

Such a coordinate transformation can be represented by a square matrix of arbitrary size. Point coordinates must have a dimension equal to the matrix size minus one. For example a square matrix of size 4×4 is used for transforming three-dimensional coordinates. The transformed points (x',y',z') are computed as below (note that this computation is similar to PerspectiveTransform in Java Advanced Imaging):

x' = u/t y' = v/t y' = w/t

where (u,v,w) are obtained by:

┌ ┐ ┌ ┐ ┌ ┐ │ u │ │ m00 m01 m02 m03 │ │ x │ │ v │ = │ m10 m11 m12 m13 │ │ y │ │ w │ │ m20 m21 m22 m23 │ │ z │ │ t │ │ m30 m31 m32 m33 │ │ 1 │ └ ┘ └ ┘ └ ┘

In the special case of an affine transform, the last row contains only zero values except in the last column, which contains 1.

See any of the following providers for a list of programmatic parameters:

• Affine - "Affine general parametric transformation" (EPSG 9624) with default matrix size of 3×3.
• LongitudeRotation - "Longitude rotation" (EPSG 9601)

Since:

1.2

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

PerspectiveTransform, AffineTransform, Affine transformation on MathWorld, 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

Fields inherited from class FormattableObject

EPSG, GEOTIFF, INTERNAL, OGC, SINGLE_LINE

Constructor Summary

protected

ProjectiveTransform(Matrix matrix) Constructs a transform from the specified matrix.

Method Summary

protected int	computeHashCode() Computes a hash value for this transform.
static LinearTransform	create(AffineTransform matrix) Deprecated. Moved to MathTransforms.linear(AffineTransform).
static LinearTransform	create(Matrix matrix) Creates a transform for the specified matrix.
static LinearTransform	createScale(int dimension, double scale) Deprecated. Moved to MathTransforms.linear(int, double, double).
static XMatrix	createSelectMatrix(int sourceDim, int[] toKeep) Deprecated. Moved to Matrices.createDimensionFilter(int, int[]) and MathTransforms.dimensionFilter(int, int[]).
static LinearTransform	createTranslation(int dimension, double offset) Deprecated. Moved to MathTransforms.linear(int, double, double).
Matrix	derivative(DirectPosition point) Gets the derivative of this transform at a point.
Matrix	derivative(Point2D point) Gets the derivative of this transform at a point.
boolean	equals(Object object, ComparisonMode mode) Compares the specified object with this math transform for equality.
Matrix	getMatrix() Returns a copy of the matrix.
ParameterDescriptorGroup	getParameterDescriptors() Returns the parameter descriptors for this math transform.
ParameterValueGroup	getParameterValues() Returns the matrix elements as a group of parameters values.
int	getSourceDimensions() Gets the dimension of input points.
int	getTargetDimensions() Gets the dimension of output points.
static LinearTransform	identity(int dimension) Returns an identity transform of the specified dimension.
MathTransform	inverse() Creates the inverse transform of this object.
boolean	isIdentity() Tests whether this transform does not move any points.
boolean	isIdentity(double tolerance) Tests whether this transform does not move any points by using the provided tolerance.
Matrix	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) Converts a single coordinate point in a list of ordinal values, and optionally computes the derivative at that location.
void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Transforms an array of floating point coordinates by this matrix.
void	transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) Transforms an array of floating point coordinates by this matrix.
void	transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Transforms an array of floating point coordinates by this matrix.
void	transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) Transforms an array of floating point coordinates by this matrix.

Methods inherited from class AbstractMathTransform

createTransformedShape, ensureNonNull, equals, formatWKT, getName, hashCode, rollLongitude, transform, transform

Methods inherited from class FormattableObject

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

Methods inherited from class Object

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

Methods inherited from interface MathTransform

toWKT, transform

Methods inherited from interface LenientComparable

equals

Constructor Detail

ProjectiveTransform

protected ProjectiveTransform(Matrix matrix)

Constructs a transform from the specified matrix. The matrix is usually square and affine, but this is not be enforced.

Parameters:

matrix - The matrix.

Method Detail

create

public static LinearTransform create(Matrix matrix)

Creates a transform for the specified matrix. The matrix is usually square and affine, but this is not be enforced.

Parameters:

matrix - The affine transform as a matrix.

Returns:

The transform for the given matrix.

See Also:

MathTransforms.linear(Matrix)

identity

public static LinearTransform identity(int dimension)

Returns an identity transform of the specified dimension. In the special case of dimension 1 and 2, this method returns instances of LinearTransform1D or AffineTransform2D respectively.

Parameters:

dimension - The dimension of the transform to be returned.

Returns:

An identity transform of the specified dimension.

Since:

3.20

See Also:

MathTransforms.identity(int)

create

@Deprecated
public static LinearTransform create(AffineTransform matrix)

Deprecated. Moved to MathTransforms.linear(AffineTransform).

Creates a transform for the specified matrix as a Java2D object. This method is provided for inter-operability with Java2D.

Parameters:

matrix - The affine transform as a matrix.

Returns:

The transform for the given matrix.

createScale

@Deprecated
public static LinearTransform createScale(int dimension,
                                                     double scale)

Deprecated. Moved to MathTransforms.linear(int, double, double).

Creates a transform that apply a uniform scale along all axis.

Parameters:

dimension - The input and output dimensions.

scale - The scale factor.

Returns:

The scale transform.

Since:

2.3

createTranslation

@Deprecated
public static LinearTransform createTranslation(int dimension,
                                                           double offset)

Deprecated. Moved to MathTransforms.linear(int, double, double).

Creates a transform that apply the same translation along all axis.

Parameters:

dimension - The input and output dimensions.

offset - The translation.

Returns:

The offset transform.

Since:

2.3

createSelectMatrix

@Deprecated
public static XMatrix createSelectMatrix(int sourceDim,
                                                    int[] toKeep)
                                  throws IndexOutOfBoundsException

Deprecated. Moved to Matrices.createDimensionFilter(int, int[]) and MathTransforms.dimensionFilter(int, int[]).

Creates a matrix that keep only a subset of the ordinate values. The dimension of source coordinates is sourceDim and the dimension of target coordinates is toKeep.length.

Parameters:

sourceDim - the dimension of source coordinates.

toKeep - the indices of ordinate values to keep.

Returns:

The matrix to give to the create(Matrix) method in order to create the transform.

Throws:

IndexOutOfBoundsException - if a value of toKeep is lower than 0 or not smaller than sourceDim.

getParameterDescriptors

public ParameterDescriptorGroup getParameterDescriptors()

Returns the parameter descriptors for this math transform.

Specified by:

getParameterDescriptors in interface Parameterized

Overrides:

getParameterDescriptors in class AbstractMathTransform

Returns:

The parameter descriptors for this math transform, or null.

See Also:

OperationMethod.getParameters()

getParameterValues

public ParameterValueGroup getParameterValues()

Returns the matrix elements as a group of parameters values. The number of parameters depends on the matrix size. Only matrix elements different from their default value will be included in this group.

Specified by:

getParameterValues in interface Parameterized

Overrides:

getParameterValues in class AbstractMathTransform

Returns:

A copy of the parameter values for this math transform.

See Also:

SingleOperation.getParameterValues()

transform

public Matrix transform(double[] srcPts,
                        int srcOff,
                        double[] dstPts,
                        int dstOff,
                        boolean derivate)

Converts a single coordinate point in a list of ordinal values, and optionally computes the derivative at that location.

Specified by:

transform in class AbstractMathTransform

Parameters:

srcPts - The array containing the source coordinate (can not be null).

srcOff - The offset to the point to be transformed in the source array.

dstPts - the array into which the transformed coordinate is returned. May be the same than srcPts. May be null if only the derivative matrix is desired.

dstOff - The offset to the location of the transformed point that is stored in the destination array.

derivate - true for computing the derivative, or false if not needed.

Returns:

The matrix of the transform derivative at the given source position, or null if the derivate argument is false.

Since:

3.20 (derived from 3.00)

See Also:

AbstractMathTransform.derivative(DirectPosition), AbstractMathTransform.transform(DirectPosition, DirectPosition), MathTransforms.derivativeAndTransform(MathTransform, double[], int, double[], int)

transform

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

Transforms an array of floating point coordinates by this matrix. Point coordinates must have a dimension equal to Matrix.getNumCol()-1. For example, for square matrix of size 4×4, coordinate points are three-dimensional and stored in the arrays starting at the specified offset (srcOff) in the order [x0, y0, z0, x1, y1, z1..., xn, yn, zn].

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The array containing the source point coordinates.

srcOff - The offset to the first point to be transformed in the source array.

dstPts - The array into which the transformed point coordinates are returned.

dstOff - The offset to the location of the first transformed point that is stored in the destination array. The source and destination array sections can be overlaps.

numPts - The number of points to be transformed.

transform

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

Transforms an array of floating point coordinates by this matrix. Point coordinates must have a dimension equal to Matrix.getNumCol()-1. For example, for square matrix of size 4×4, coordinate points are three-dimensional and stored in the arrays starting at the specified offset (srcOff) in the order [x0, y0, z0, x1, y1, z1..., xn, yn, zn].

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The array containing the source point coordinates.

srcOff - The offset to the first point to be transformed in the source array.

dstPts - The array into which the transformed point coordinates are returned.

dstOff - The offset to the location of the first transformed point that is stored in the destination array. The source and destination array sections can be overlaps.

numPts - The number of points to be transformed.

transform

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

Transforms an array of floating point coordinates by this matrix.

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The array containing the source point coordinates.

srcOff - The offset to the first point to be transformed in the source array.

dstPts - The array into which the transformed point coordinates are returned.

dstOff - The offset to the location of the first transformed point that is stored in the destination array.

numPts - The number of points to be transformed.

transform

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

Transforms an array of floating point coordinates by this matrix.

Specified by:

transform in interface MathTransform

Overrides:

transform in class AbstractMathTransform

Parameters:

srcPts - The array containing the source point coordinates.

srcOff - The offset to the first point to be transformed in the source array.

dstPts - The array into which the transformed point coordinates are returned.

dstOff - The offset to the location of the first transformed point that is stored in the destination array.

numPts - The number of points to be transformed.

derivative

public Matrix derivative(Point2D point)

Gets the derivative of this transform at a point. For a matrix transform, the derivative is the same everywhere.

Overrides:

derivative in class AbstractMathTransform

Parameters:

point - Ignored (can be null).

Returns:

The derivative at the specified point as a 2×2 matrix.

See Also:

MathTransform2D.derivative(Point2D)

derivative

public Matrix derivative(DirectPosition point)

Gets the derivative of this transform at a point. For a matrix transform, the derivative is the same everywhere.

Specified by:

derivative in interface MathTransform

Overrides:

derivative in class AbstractMathTransform

Parameters:

point - Ignored (can be null).

Returns:

The derivative at the specified point (never null).

getMatrix

public Matrix getMatrix()

Returns a copy of the matrix.

Specified by:

getMatrix in interface LinearTransform

Returns:

A copy of the underlying matrix.

getSourceDimensions

public int getSourceDimensions()

Gets the dimension of input points.

Specified by:

getSourceDimensions in interface MathTransform

Specified by:

getSourceDimensions in class AbstractMathTransform

getTargetDimensions

public int getTargetDimensions()

Gets the dimension of output points.

Specified by:

getTargetDimensions in interface MathTransform

Specified by:

getTargetDimensions in class AbstractMathTransform

isIdentity

public boolean isIdentity()

Tests whether this transform does not move any points.

Specified by:

isIdentity in interface MathTransform

Overrides:

isIdentity in class AbstractMathTransform

isIdentity

public boolean isIdentity(double tolerance)

Tests whether this transform does not move any points by using the provided tolerance. This method work in the same way than XMatrix.isIdentity(double).

Specified by:

isIdentity in interface LinearTransform

Parameters:

tolerance - The tolerance factor.

Returns:

true if this transform is the identity one

Since:

2.4

See Also:

Matrices.getMatrix(MathTransform), XMatrix.isIdentity(double)

inverse

public MathTransform inverse()
                      throws NoninvertibleTransformException

Creates the inverse transform of this object.

Specified by:

inverse in interface MathTransform

Overrides:

inverse in class AbstractMathTransform

Throws:

NoninvertibleTransformException

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 the specified object with this math transform for equality. The default implementation returns true if the following conditions are meet:

• object is an instance of the same class than this. We require the same class because there is no interface for the various kinds of transform.
• The parameter descriptors are equal according the given comparison mode.

The parameter values are not compared because subclasses can typically compare those values more efficiently by accessing to their member fields.

Specified by:

equals in interface LinearTransform

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.

See Also:

Utilities.deepEquals(Object, Object, ComparisonMode)