Class AffineTransformation

Namespace: NetTopologySuite.Geometries.Utilities

Assembly: NetTopologySuite.dll

Represents an affine transformation on the 2D Cartesian plane.

public class AffineTransformation : ICloneable, ICoordinateSequenceFilter, IEquatable<AffineTransformation>

Inheritance: object

AffineTransformation

Implements: ICloneable

ICoordinateSequenceFilter

IEquatable<AffineTransformation>

Inherited Members: object.GetType()

object.MemberwiseClone()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

It can be used to transform a Coordinate or Geometry. An affine transformation is a mapping of the 2D plane into itself via a series of transformations of the following basic types:

reflection (through a line)
rotation (around the origin)
scaling (relative to the origin)
shearing (in both the X and Y directions)
translation

In general, affine transformations preserve straightness and parallel lines, but do not preserve distance or shape.

An affine transformation can be represented by a 3x3 matrix in the following form:

T = | m00 m01 m02 |
                | m10 m11 m12 |
                |  0   0   1  |

A coordinate P = (x, y) can be transformed to a new coordinate P' = (x', y') by representing it as a 3x1 matrix and using matrix multiplication to compute:

| x' |  = T x | x |
            | y' |        | y |
            | 1  |        | 1 |

Transformation Composition

Affine transformations can be composed using the Compose(AffineTransformation) method. Composition is computed via multiplication of the transformation matrices, and is defined as:

A.compose(B) = T_B x T_A

This produces a transformation whose effect is that of A followed by B. The methods Reflect(double, double, double, double), Rotate(double), Scale(double, double), Shear(double, double), and Translate(double, double) have the effect of composing a transformation of that type with the transformation they are invoked on. The composition of transformations is in general not commutative.

Transformation Inversion

Affine transformations may be invertible or non-invertible. If a transformation is invertible, then there exists an inverse transformation which when composed produces the identity transformation. The GetInverse() method computes the inverse of a transformation, if one exists.

@author Martin Davis

Constructors

AffineTransformation()

Constructs a new identity transformation

public AffineTransformation()

AffineTransformation(Coordinate, Coordinate, Coordinate, Coordinate, Coordinate, Coordinate)

Constructs a transformation which maps the given source points into the given destination points.

public AffineTransformation(Coordinate src0, Coordinate src1, Coordinate src2, Coordinate dest0, Coordinate dest1, Coordinate dest2)

Parameters

src0 Coordinate: source point 0
src1 Coordinate: source point 1
src2 Coordinate: source point 2
dest0 Coordinate: the mapped point for source point 0
dest1 Coordinate: the mapped point for source point 1
dest2 Coordinate: the mapped point for source point 2

AffineTransformation(AffineTransformation)

Constructs a transformation which is a copy of the given one.

public AffineTransformation(AffineTransformation trans)

Parameters

trans AffineTransformation: the transformation to copy

AffineTransformation(double, double, double, double, double, double)

Constructs a new transformation whose matrix has the specified values.

public AffineTransformation(double m00, double m01, double m02, double m10, double m11, double m12)

Parameters

m00 double: the entry for the [0, 0] element in the transformation matrix
m01 double: the entry for the [0, 1] element in the transformation matrix
m02 double: the entry for the [0, 2] element in the transformation matrix
m10 double: the entry for the [1, 0] element in the transformation matrix
m11 double: the entry for the [1, 1] element in the transformation matrix
m12 double: the entry for the [1, 2] element in the transformation matrix

AffineTransformation(double[])

Constructs a new transformation whose matrix has the specified values.

public AffineTransformation(double[] matrix)

Parameters

matrix double[]: an array containing the 6 values { m00, m01, m02, m10, m11, m12 }

Exceptions

NullReferenceException: if matrix is null
IndexOutOfRangeException: if matrix is too small

Properties

Determinant

Computes the determinant of the transformation matrix.

public double Determinant { get; }

Property Value

double: the determinant of the transformation

Remarks

The determinant is computed as:

| m00 m01 m02 |
            | m10 m11 m12 | = m00 * m11 - m01 * m10
            |  0   0   1  |

If the determinant is zero, the transform is singular (not invertible), and operations which attempt to compute an inverse will throw a NoninvertibleTransformationException.

Done

Reports that this filter should continue to be executed until all coordinates have been transformed.

public bool Done { get; }

Property Value

bool: false

GeometryChanged

public bool GeometryChanged { get; }

Property Value

bool

IsIdentity

Tests if this transformation is the identity transformation.

public bool IsIdentity { get; }

Property Value

bool

MatrixEntries

Gets an array containing the entries of the transformation matrix.

public double[] MatrixEntries { get; }

Property Value

double[]: an array of length 6

Remarks

Only the 6 non-trivial entries are returned, in the sequence:

m00, m01, m02, m10, m11, m12

Methods

Clone()

Clones this transformation

public object Clone()

Returns

object: A copy of this transformation

Compose(AffineTransformation)

Updates this transformation to be the composition of this transformation with the given AffineTransformation.

public AffineTransformation Compose(AffineTransformation trans)

Parameters

trans AffineTransformation: an affine transformation

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

This produces a transformation whose effect is equal to applying this transformation followed by the argument transformation. Mathematically,

A.compose(B) = T_B x T_A

ComposeBefore(AffineTransformation)

Updates this transformation to be the composition of a given AffineTransformation with this transformation.

public AffineTransformation ComposeBefore(AffineTransformation trans)

Parameters

trans AffineTransformation: an affine transformation

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

This produces a transformation whose effect is equal to applying the argument transformation followed by this transformation. Mathematically,

A.composeBefore(B) = T_A x T_B

Equals(AffineTransformation)

public bool Equals(AffineTransformation trans)

Parameters

trans AffineTransformation

Returns

bool

Equals(object)

Tests if an object is an AffineTransformation and has the same matrix as this transformation.

public override bool Equals(object obj)

Parameters

obj object: An object to test

Returns

bool: true if the given object is equal to this object

Filter(CoordinateSequence, int)

Transforms the i'th coordinate in the input sequence

public void Filter(CoordinateSequence seq, int i)

Parameters

seq CoordinateSequence: A CoordinateSequence
i int: The index of the coordinate to transform

GetHashCode()

public override int GetHashCode()

Returns

int

GetInverse()

Computes the inverse of this transformation, if one exists.

public AffineTransformation GetInverse()

Returns

AffineTransformation: A new inverse transformation

Remarks

The inverse is the transformation which when composed with this one produces the identity transformation. A transformation has an inverse if and only if it is not singular (i.e. its determinant is non-zero). Geometrically, an transformation is non-invertible if it maps the plane to a line or a point. If no inverse exists this method will throw a NoninvertibleTransformationException.

The matrix of the inverse is equal to the inverse of the matrix for the transformation. It is computed as follows:

                1
            inverse(A)  =  ---   x  adjoint(A)
                           det
                    =   1       |  m11  -m01   m01*m12-m02*m11  |
                       ---   x  | -m10   m00  -m00*m12+m10*m02  |
                       det      |  0     0     m00*m11-m10*m01  |



                    = |  m11/det  -m01/det   m01*m12-m02*m11/det |
                      | -m10/det   m00/det  -m00*m12+m10*m02/det |
                      |   0           0          1               |</code></pre></blockquote>

Exceptions

NoninvertibleTransformationException

Reflect(double, double)

Updates the value of this transformation to that of a reflection transformation composed with the current value.

public AffineTransformation Reflect(double x, double y)

Parameters

x double: the x-ordinate of the line to reflect around
y double: the y-ordinate of the line to reflect around

Returns

AffineTransformation: this transformation, with an updated matrix

Reflect(double, double, double, double)

Updates the value of this transformation to that of a reflection transformation composed with the current value.

public AffineTransformation Reflect(double x0, double y0, double x1, double y1)

Parameters

x0 double: the x-ordinate of a point on the line to reflect around
y0 double: the y-ordinate of a point on the line to reflect around
x1 double: the x-ordinate of a point on the line to reflect around
y1 double: the y-ordinate of a point on the line to reflect around

Returns

AffineTransformation: this transformation, with an updated matrix

ReflectionInstance(double, double)

Creates a transformation for a reflection about the line (0,0) - (x,y).

public static AffineTransformation ReflectionInstance(double x, double y)

Parameters

x double: the x-ordinate of a point on the reflection line
y double: the y-ordinate of a point on the reflection line

Returns

AffineTransformation: a transformation for the reflection

ReflectionInstance(double, double, double, double)

Creates a transformation for a reflection about the line (x0,y0) - (x1,y1).

public static AffineTransformation ReflectionInstance(double x0, double y0, double x1, double y1)

Parameters

x0 double: the x-ordinate of a point on the reflection line
y0 double: the y-ordinate of a point on the reflection line
x1 double: the x-ordinate of a another point on the reflection line
y1 double: the y-ordinate of a another point on the reflection line

Returns

AffineTransformation: a transformation for the reflection

Rotate(double)

Updates the value of this transformation to that of a rotation transformation composed with the current value.

public AffineTransformation Rotate(double theta)

Parameters

theta double: the angle to rotate by in radians

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

Positive angles correspond to a rotation in the counter-clockwise direction.

Rotate(double, double)

Updates the value of this transformation to that of a rotation around the origin composed with the current value, with the sin and cos of the rotation angle specified directly.

public AffineTransformation Rotate(double sinTheta, double cosTheta)

Parameters

sinTheta double: the sine of the angle to rotate by
cosTheta double: the cosine of the angle to rotate by

Returns

AffineTransformation: this transformation, with an updated matrix

Rotate(double, double, double)

Updates the value of this transformation to that of a rotation around a given point composed with the current value.

public AffineTransformation Rotate(double theta, double x, double y)

Parameters

theta double: the angle to rotate by, in radians
x double: the x-ordinate of the rotation point
y double: the y-ordinate of the rotation point

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

Positive angles correspond to a rotation in the counter-clockwise direction.

Rotate(double, double, double, double)

Updates the value of this transformation to that of a rotation around a given point composed with the current value, with the sin and cos of the rotation angle specified directly.

public AffineTransformation Rotate(double sinTheta, double cosTheta, double x, double y)

Parameters

sinTheta double: the sine of the angle to rotate by
cosTheta double: the cosine of the angle to rotate by
x double: the x-ordinate of the rotation point
y double: the y-ordinate of the rotation point

Returns

AffineTransformation: this transformation, with an updated matrix

RotationInstance(double)

Creates a transformation for a rotation about the origin by an angle theta.

public static AffineTransformation RotationInstance(double theta)

Parameters

theta double: the rotation angle, in radians

Returns

AffineTransformation: a transformation for the rotation

Remarks

Positive angles correspond to a rotation in the counter-clockwise direction.

RotationInstance(double, double)

Creates a transformation for a rotation by an angle theta, specified by the sine and cosine of the angle.

public static AffineTransformation RotationInstance(double sinTheta, double cosTheta)

Parameters

sinTheta double: the sine of the rotation angle
cosTheta double: the cosine of the rotation angle

Returns

AffineTransformation: a transformation for the rotation

Remarks

This allows providing exact values for sin(theta) and cos(theta) for the common case of rotations of multiples of quarter-circles.

RotationInstance(double, double, double)

Creates a transformation for a rotation about the point (x,y) by an angle theta.

public static AffineTransformation RotationInstance(double theta, double x, double y)

Parameters

theta double: the rotation angle, in radians
x double: the x-ordinate of the rotation point
y double: the y-ordinate of the rotation point

Returns

AffineTransformation: a transformation for the rotation

Remarks

Positive angles correspond to a rotation in the counter-clockwise direction.

RotationInstance(double, double, double, double)

Creates a transformation for a rotation about the point (x,y) by an angle theta, specified by the sine and cosine of the angle.

public static AffineTransformation RotationInstance(double sinTheta, double cosTheta, double x, double y)

Parameters

sinTheta double: the sine of the rotation angle
cosTheta double: the cosine of the rotation angle
x double: the x-ordinate of the rotation point
y double: the y-ordinate of the rotation point

Returns

AffineTransformation: a transformation for the rotation

Remarks

This allows providing exact values for sin(theta) and cos(theta) for the common case of rotations of multiples of quarter-circles.

Scale(double, double)

Updates the value of this transformation to that of a scale transformation composed with the current value.

public AffineTransformation Scale(double xScale, double yScale)

Parameters

xScale double: the value to scale by in the x direction
yScale double: the value to scale by in the y direction

Returns

AffineTransformation: this transformation, with an updated matrix

ScaleInstance(double, double)

Creates a transformation for a scaling relative to the origin.

public static AffineTransformation ScaleInstance(double xScale, double yScale)

Parameters

xScale double: the value to scale by in the x direction
yScale double: the value to scale by in the y direction

Returns

AffineTransformation: a transformation for the scaling

ScaleInstance(double, double, double, double)

Creates a transformation for a scaling relative to the point (x,y).

public static AffineTransformation ScaleInstance(double xScale, double yScale, double x, double y)

Parameters

xScale double: The value to scale by in the x direction
yScale double: The value to scale by in the y direction
x double: The x-ordinate of the point to scale around
y double: The y-ordinate of the point to scale around

Returns

AffineTransformation: A transformation for the scaling

SetToIdentity()

Sets this transformation to be the identity transformation.

public AffineTransformation SetToIdentity()

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

The identity transformation has the matrix:

| 1 0 0 |
            | 0 1 0 |
            | 0 0 1 |

SetToReflection(double, double)

Sets this transformation to be a reflection about the line defined by vector (x,y).

public AffineTransformation SetToReflection(double x, double y)

Parameters

x double: the x-component of the reflection line vector
y double: the y-component of the reflection line vector

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

The transformation for a reflection is computed by:

d = sqrt(x2 + y2)
            sin = x / d;
            cos = x / d;
            Tref = Trot(sin, cos) x Tscale(1, -1) x Trot(-sin, cos)

SetToReflection(double, double, double, double)

Sets this transformation to be a reflection about the line defined by a line (x0,y0) - (x1,y1).

public AffineTransformation SetToReflection(double x0, double y0, double x1, double y1)

Parameters

x0 double: The x-ordinate of one point on the reflection line
y0 double: The y-ordinate of one point on the reflection line
x1 double: The x-ordinate of another point on the reflection line
y1 double: The y-ordinate of another point on the reflection line

Returns

AffineTransformation: This transformation with an updated matrix

SetToReflectionBasic(double, double, double, double)

Explicitly computes the math for a reflection. May not work.

public AffineTransformation SetToReflectionBasic(double x0, double y0, double x1, double y1)

Parameters

x0 double: The x-ordinate of one point on the reflection line
y0 double: The y-ordinate of one point on the reflection line
x1 double: The x-ordinate of another point on the reflection line
y1 double: The y-ordinate of another point on the reflection line

Returns

AffineTransformation: This transformation with an updated matrix

SetToRotation(double)

Sets this transformation to be a rotation around the orign.

public AffineTransformation SetToRotation(double theta)

Parameters

theta double: the rotation angle, in radians

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

A positive rotation angle corresponds to a counter-clockwise rotation. The transformation matrix for a rotation by an angle theta has the value:

|  cos(theta)  -sin(theta)   0 |
|  sin(theta)   cos(theta)   0 |
|           0            0   1 |

SetToRotation(double, double)

Sets this transformation to be a rotation around the origin by specifying the sin and cos of the rotation angle directly.

public AffineTransformation SetToRotation(double sinTheta, double cosTheta)

Parameters

sinTheta double: the sine of the rotation angle
cosTheta double: the cosine of the rotation angle

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

The transformation matrix for the rotation has the value:

|  cosTheta  -sinTheta   0 |
|  sinTheta   cosTheta   0 |
|         0          0   1 |

SetToRotation(double, double, double)

Sets this transformation to be a rotation around a given point (x,y).

public AffineTransformation SetToRotation(double theta, double x, double y)

Parameters

theta double: the rotation angle, in radians
x double: the x-ordinate of the rotation point
y double: the y-ordinate of the rotation point

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

A positive rotation angle corresponds to a counter-clockwise rotation. The transformation matrix for a rotation by an angle theta has the value:

|  cosTheta  -sinTheta   x-x*cos+y*sin |
|  sinTheta   cosTheta   y-x*sin-y*cos |
|           0            0   1 |

SetToRotation(double, double, double, double)

Sets this transformation to be a rotation around a given point (x,y) by specifying the sin and cos of the rotation angle directly.

public AffineTransformation SetToRotation(double sinTheta, double cosTheta, double x, double y)

Parameters

sinTheta double: the sine of the rotation angle
cosTheta double: the cosine of the rotation angle
x double: the x-ordinate of the rotation point
y double: the y-ordinate of the rotation point

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

The transformation matrix for the rotation has the value:

|  cosTheta  -sinTheta   x-x*cos+y*sin |
|  sinTheta   cosTheta   y-x*sin-y*cos |
|         0          0         1       |

SetToScale(double, double)

Sets this transformation to be a scaling.

public AffineTransformation SetToScale(double xScale, double yScale)

Parameters

xScale double: the amount to scale x-ordinates by
yScale double: the amount to scale y-ordinates by

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

The transformation matrix for a scale has the value:

|  xScale      0  dx |
|  0      yScale  dy |
|  0           0   1 |

SetToShear(double, double)

Sets this transformation to be a shear.

public AffineTransformation SetToShear(double xShear, double yShear)

Parameters

xShear double: the x component to shear by
yShear double: the y component to shear by

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

The transformation matrix for a shear has the value:

|  1      xShear  0 |
|  yShear      1  0 |
|  0           0  1 |

Note that a shear of (1, 1) is not equal to shear(1, 0) composed with shear(0, 1). Instead, shear(1, 1) corresponds to a mapping onto the line x = y.

SetToTranslation(double, double)

Sets this transformation to be a translation.

public AffineTransformation SetToTranslation(double dx, double dy)

Parameters

dx double: the x component to translate by
dy double: the y component to translate by

Returns

AffineTransformation: this transformation, with an updated matrix

Remarks

For a translation by the vector (x, y) the transformation matrix has the value:

|  1  0  dx |
|  1  0  dy |
|  0  0   1 |

SetTransformation(AffineTransformation)

Sets this transformation to be a copy of the given one

public AffineTransformation SetTransformation(AffineTransformation trans)

Parameters

trans AffineTransformation: a transformation to copy

Returns

AffineTransformation: this transformation, with an updated matrix

SetTransformation(double, double, double, double, double, double)

Sets this transformation's matrix to have the given values.

public AffineTransformation SetTransformation(double m00, double m01, double m02, double m10, double m11, double m12)

Parameters

m00 double: the entry for the [0, 0] element in the transformation matrix
m01 double: the entry for the [0, 1] element in the transformation matrix
m02 double: the entry for the [0, 2] element in the transformation matrix
m10 double: the entry for the [1, 0] element in the transformation matrix
m11 double: the entry for the [1, 1] element in the transformation matrix
m12 double: the entry for the [1, 2] element in the transformation matrix

Returns

AffineTransformation: this transformation, with an updated matrix

Shear(double, double)

Updates the value of this transformation to that of a shear transformation composed with the current value.

public AffineTransformation Shear(double xShear, double yShear)

Parameters

xShear double: the value to shear by in the x direction
yShear double: the value to shear by in the y direction

Returns

AffineTransformation: this transformation, with an updated matrix

ShearInstance(double, double)

Creates a transformation for a shear.

public static AffineTransformation ShearInstance(double xShear, double yShear)

Parameters

xShear double: the value to shear by in the x direction
yShear double: the value to shear by in the y direction

Returns

AffineTransformation: a transformation for the shear

ToString()

Gets a text representation of this transformation. The string is of the form:

AffineTransformation[[m00, m01, m02], [m10, m11, m12]]

public override string ToString()

Returns

string: A string representing this transformation

Transform(Coordinate, Coordinate)

Applies this transformation to the src coordinate and places the results in the dest coordinate (which may be the same as the source).

public Coordinate Transform(Coordinate src, Coordinate dest)

Parameters

src Coordinate: the coordinate to transform
dest Coordinate: the coordinate to accept the results

Returns

Coordinate: the dest coordinate

Transform(CoordinateSequence, int)

Applies this transformation to the i'th coordinate in the given CoordinateSequence.

public void Transform(CoordinateSequence seq, int i)

Parameters

seq CoordinateSequence: a CoordinateSequence
i int: the index of the coordinate to transform

Transform(Geometry)

Creates a new Geometry which is the result of this transformation applied to the input Geometry.

public Geometry Transform(Geometry g)

Parameters

g Geometry: A Geometry

Returns

Geometry: The transformed Geometry

Translate(double, double)

Updates the value of this transformation to that of a translation transformation composed with the current value.

public AffineTransformation Translate(double x, double y)

Parameters

x double: the value to translate by in the x direction
y double: the value to translate by in the y direction

Returns

AffineTransformation: this transformation, with an updated matrix

TranslationInstance(double, double)

Creates a transformation for a translation.

public static AffineTransformation TranslationInstance(double x, double y)

Parameters

x double: the value to translate by in the x direction
y double: the value to translate by in the y direction

Returns

AffineTransformation: a transformation for the translation

Table of Contents

Class AffineTransformation

Remarks

Transformation Composition

Transformation Inversion

Constructors

AffineTransformation()

AffineTransformation(Coordinate, Coordinate, Coordinate, Coordinate, Coordinate, Coordinate)

Parameters

AffineTransformation(AffineTransformation)

Parameters

AffineTransformation(double, double, double, double, double, double)

Parameters

AffineTransformation(double[])

Parameters

Exceptions

Properties

Determinant

Property Value

Remarks

Done

Property Value

GeometryChanged

Property Value

IsIdentity

Property Value

MatrixEntries

Property Value

Remarks

Methods

Clone()

Returns

Compose(AffineTransformation)

Parameters

Returns

Remarks

ComposeBefore(AffineTransformation)

Parameters

Returns

Remarks

Equals(AffineTransformation)

Parameters

Returns

Equals(object)

Parameters

Returns

Filter(CoordinateSequence, int)

Parameters

GetHashCode()

Returns

GetInverse()

Returns

Remarks

Exceptions

Reflect(double, double)

Parameters

Returns

Reflect(double, double, double, double)

Parameters

Returns

ReflectionInstance(double, double)

Parameters

Returns

ReflectionInstance(double, double, double, double)

Parameters

Returns

Rotate(double)

Parameters

Returns

Remarks

Rotate(double, double)

Parameters

Returns

Rotate(double, double, double)

Parameters

Returns

Remarks

Rotate(double, double, double, double)

Parameters

Returns