Package org.geotools.referencing.operation.transform

Class ProjectiveTransform

Object
Formattable
AbstractMathTransform
ProjectiveTransform
All Implemented Interfaces:
Serializable, MathTransform, LinearTransform
Direct Known Subclasses:
GeocentricTranslation
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 an arbitrary size. Point coordinates must have a dimension equals to Matrix.getNumCol()-1. For example, for square matrix of size 4×4, coordinate points are three-dimensional. The transformed points (x',y',z') are computed as below (note that this computation is similar to PerspectiveTransform in Java Advanced Imaging): 

 [ u ]     [ m00  m01  m02  m03 ] [ x ]
 [ v ]  =  [ m10  m11  m12  m13 ] [ y ]
 [ w ]     [ m20  m21  m22  m23 ] [ z ]
 [ t ]     [ m30  m31  m32  m33 ] [ 1 ]

   x' = u/t
   y' = v/t
   y' = w/t
In the special case of an affine transform, the last row contains only zero values except in the last column, which contains 1.
Since:
2.0
Author:
Martin Desruisseaux (IRD)
See Also:

  • Constructor Details

    • ProjectiveTransform

      protected ProjectiveTransform(Matrix matrix)
      Constructs a transform from the specified matrix. The matrix should be affine, but it will not be verified.
      Parameters:
      matrix - The matrix.

  • Method Details

    • create

      public static LinearTransform create(Matrix matrix)
      Creates a transform for the specified matrix. The matrix should be affine, but it is not be verified.
      Parameters:
      matrix - The affine transform as a matrix.
      Returns:
      The transform for the given matrix.

    • create

      public static LinearTransform create(AffineTransform matrix)
      Creates a transform for the specified matrix as a Java2D object. This method is provided for interoperability with Java2D.
      Parameters:
      matrix - The affine transform as a matrix.
      Returns:
      The transform for the given matrix.

    • createScale

      public static LinearTransform createScale(int dimension, double scale)
      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

      public static LinearTransform createTranslation(int dimension, double offset)
      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

      public static Matrix createSelectMatrix(int sourceDim, int[] toKeep) throws IndexOutOfBoundsException
      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.
      Overrides:
      getParameterDescriptors in class AbstractMathTransform
      Returns:
      The parameter descriptors for this math transform, or null.
      See Also:

    • 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.
      Overrides:
      getParameterValues in class AbstractMathTransform
      Returns:
      A copy of the parameter values for this math transform.
      See Also:

    • 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 equals 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, double[] dstPts, int dstOff, int numPts)
      Transforms an array of floating point coordinates by this matrix. Point coordinates must have a dimension equals 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
      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

    • 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 - The coordinate point where to evaluate the derivative.
      Returns:
      The derivative at the specified point as a 2×2 matrix.
      See Also:

    • derivative

      public Matrix derivative(Position 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 - The coordinate point where to evaluate the derivative.
      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
      Returns:
      The dimension of input points.

    • getTargetDimensions

      public int getTargetDimensions()
      Gets the dimension of output points.
      Specified by:
      getTargetDimensions in interface MathTransform
      Specified by:
      getTargetDimensions in class AbstractMathTransform
      Returns:
      The dimension of output points.

    • isIdentity

      public boolean isIdentity()
      Tests whether this transform does not move any points.
      Specified by:
      isIdentity in interface MathTransform
      Overrides:
      isIdentity in class AbstractMathTransform
      Returns:
      true if this MathTransform is an identity transform; false otherwise.

    • 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

    • inverse

      public MathTransform inverse() throws NoninvertibleTransformException
      Creates the inverse transform of this object.
      Specified by:
      inverse in interface MathTransform
      Overrides:
      inverse in class AbstractMathTransform
      Returns:
      The inverse transform.
      Throws:
      NoninvertibleTransformException - if the transform can't be inversed.

    • hashCode

      public int hashCode()
      Returns a hash value for this transform. This value need not remain consistent between different implementations of the same class.
      Overrides:
      hashCode in class AbstractMathTransform

    • equals

      public boolean equals(Object object)
      Compares the specified object with this math transform for equality.
      Overrides:
      equals in class AbstractMathTransform
      Parameters:
      object - The object to compare with this transform.
      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.