Meziantou.Framework

ProjectiveTransform Struct

Namespace
Meziantou.Framework.Imaging
Assembly
Meziantou.Framework.Imaging.dll
Package
Meziantou.Framework.Imaging 1.2.11
Source
ProjectiveTransform.cs
Available in package assets
net10.0net11.0

A transformation of the plane that keeps straight lines straight, but not parallel lines parallel: a plane seen in perspective. An AffineTransform is the projective transformation whose third column is (0, 0, 1).

public readonly struct ProjectiveTransform : IEquatable<ProjectiveTransform>

Remarks

A point (x, y) becomes (X / W, Y / W), with X = x M11 + y M21 + M31, Y = x M12 + y M22 + M32 and W = x M13 + y M23 + M33: the convention of AffineTransform, whose offsets are M31 and M32. The default value is the identity.

The points where W is positive are in front of the viewer; those where it is zero or negative have no image, and are not drawn: a drawing that crosses that line (the horizon of the plane) is cut there. Multiplying every coefficient by the same positive number does not change the transformation.

Implements

Constructors

NameDescription
ProjectiveTransform(double, double, double, double, double, double, double, double, double)Initializes a new instance of the ProjectiveTransform struct from its coefficients.

ProjectiveTransform(double, double, double, double, double, double, double, double, double)

ProjectiveTransform.cs

Initializes a new instance of the ProjectiveTransform struct from its coefficients.

public ProjectiveTransform(double m11, double m12, double m13, double m21, double m22, double m23, double m31, double m32, double m33)

Parameters

m11 double
The factor of x in X.
m12 double
The factor of x in Y.
m13 double
The factor of x in W.
m21 double
The factor of y in X.
m22 double
The factor of y in Y.
m23 double
The factor of y in W.
m31 double
The constant of X: the horizontal translation of an affine transformation.
m32 double
The constant of Y: the vertical translation of an affine transformation.
m33 double
The constant of W.

Exceptions

ArgumentException
A coefficient is not a finite number.

Properties

NameDescription
DeterminantGets the determinant of the nine coefficients: zero when the transformation flattens the plane to a line or a point.
IdentityGets the transformation that changes nothing.
IsAffineGets a value indicating whether the transformation is affine: W is the same positive number everywhere, so parallel lines stay parallel and every point has an image.
IsIdentityGets a value indicating whether the transformation changes nothing.
M11Gets the factor of x in X.
M12Gets the factor of x in Y.
M13Gets the factor of x in W.
M21Gets the factor of y in X.
M22Gets the factor of y in Y.
M23Gets the factor of y in W.
M31Gets the constant of X.
M32Gets the constant of Y.
M33Gets the constant of W.

Determinant

ProjectiveTransform.cs

Gets the determinant of the nine coefficients: zero when the transformation flattens the plane to a line or a point.

public double Determinant { get; }

Property value

double

Identity

ProjectiveTransform.cs

Gets the transformation that changes nothing.

public static ProjectiveTransform Identity { get; }

Property value

ProjectiveTransform

IsAffine

ProjectiveTransform.cs

Gets a value indicating whether the transformation is affine: W is the same positive number everywhere, so parallel lines stay parallel and every point has an image.

public bool IsAffine { get; }

Property value

bool

IsIdentity

ProjectiveTransform.cs

Gets a value indicating whether the transformation changes nothing.

public bool IsIdentity { get; }

Property value

bool

M11

ProjectiveTransform.cs

Gets the factor of x in X.

public double M11 { get; }

Property value

double

M12

ProjectiveTransform.cs

Gets the factor of x in Y.

public double M12 { get; }

Property value

double

M13

ProjectiveTransform.cs

Gets the factor of x in W.

public double M13 { get; }

Property value

double

M21

ProjectiveTransform.cs

Gets the factor of y in X.

public double M21 { get; }

Property value

double

M22

ProjectiveTransform.cs

Gets the factor of y in Y.

public double M22 { get; }

Property value

double

M23

ProjectiveTransform.cs

Gets the factor of y in W.

public double M23 { get; }

Property value

double

M31

ProjectiveTransform.cs

Gets the constant of X.

public double M31 { get; }

Property value

double

M32

ProjectiveTransform.cs

Gets the constant of Y.

public double M32 { get; }

Property value

double

M33

ProjectiveTransform.cs

Gets the constant of W.

public double M33 { get; }

Property value

double

Methods

NameDescription
CreateFromQuadrilateral(RectangleD, PointD, PointD, PointD, PointD)Creates the transformation that maps the corners of a rectangle to the corners of a quadrilateral: the rectangle seen in perspective.
Equals(ProjectiveTransform)Indicates whether the current object is equal to another object of the same type.
Equals(object?)Indicates whether this instance and a specified object are equal.
GetHashCode()Returns the hash code for this instance.
Multiply(ProjectiveTransform, ProjectiveTransform)Gets the transformation that applies a first one, then a second one.
Then(ProjectiveTransform)Gets the transformation that applies this one first, then another one.
ToString()Returns the coefficients formatted as [M11 M12 M13 M21 M22 M23 M31 M32 M33].
TryInvert(ProjectiveTransform)Gets the transformation that undoes this one.
TryTransform(PointD, PointD)Transforms a point.

CreateFromQuadrilateral(RectangleD, PointD, PointD, PointD, PointD)

ProjectiveTransform.cs

Creates the transformation that maps the corners of a rectangle to the corners of a quadrilateral: the rectangle seen in perspective.

public static ProjectiveTransform CreateFromQuadrilateral(RectangleD source, PointD topLeft, PointD topRight, PointD bottomRight, PointD bottomLeft)

Parameters

source RectangleD
The rectangle. Must not be empty.
topLeft PointD
Where the top-left corner of the rectangle goes.
topRight PointD
Where the top-right corner goes.
bottomRight PointD
Where the bottom-right corner goes.
bottomLeft PointD
Where the bottom-left corner goes.

Returns

ProjectiveTransform The transformation; W is positive inside the quadrilateral.

Exceptions

ArgumentException
A coordinate is not a finite number, the rectangle is empty, or the points are not the corners of a convex quadrilateral, in order around it.

Equals overloads

Equals(ProjectiveTransform)

ProjectiveTransform.cs

Indicates whether the current object is equal to another object of the same type.

public bool Equals(ProjectiveTransform other)
Parameters
other ProjectiveTransform
An object to compare with this object.
Returns

bool true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

ProjectiveTransform.cs

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)
Parameters
obj object?
The object to compare with the current instance.
Returns

bool true if obj and this instance are the same type and represent the same value; otherwise, false.

GetHashCode()

ProjectiveTransform.cs

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int A 32-bit signed integer that is the hash code for this instance.

Multiply(ProjectiveTransform, ProjectiveTransform)

ProjectiveTransform.cs

Gets the transformation that applies a first one, then a second one.

public static ProjectiveTransform Multiply(ProjectiveTransform first, ProjectiveTransform second)

Parameters

first ProjectiveTransform
The transformation applied first.
second ProjectiveTransform
The transformation applied to the result of the first one.

Returns

ProjectiveTransform The combined transformation.

Exceptions

ArgumentException
A coefficient of the result is not a finite number.

Then(ProjectiveTransform)

ProjectiveTransform.cs

Gets the transformation that applies this one first, then another one.

public ProjectiveTransform Then(ProjectiveTransform next)

Parameters

next ProjectiveTransform
The transformation applied after this one.

Returns

ProjectiveTransform The combined transformation.

Exceptions

ArgumentException
A coefficient of the result is not a finite number.

ToString()

ProjectiveTransform.cs

Returns the coefficients formatted as [M11 M12 M13 M21 M22 M23 M31 M32 M33].

public override string ToString()

Returns

string A string representation of the transformation.

TryInvert(ProjectiveTransform)

ProjectiveTransform.cs

Gets the transformation that undoes this one.

public bool TryInvert(out ProjectiveTransform inverse)

Parameters

inverse ProjectiveTransform
The inverse transformation, or the identity when there is none.

Returns

bool false when the transformation flattens the plane to a line or a point: nothing undoes it.

Remarks

The inverse keeps the sign of W: a point in front of the viewer comes back with a positive W.

TryTransform(PointD, PointD)

ProjectiveTransform.cs

Transforms a point.

public bool TryTransform(PointD point, out PointD result)

Parameters

point PointD
The point.
result PointD
The transformed point, or the origin when the point has no image.

Returns

bool false when W is not positive at the point: it is on or behind the horizon, and has no image.

Operators

NameDescription
operator ==(ProjectiveTransform, ProjectiveTransform)Compares two transformations for equality.
implicit operator ProjectiveTransform(AffineTransform)Converts an affine transformation.
operator !=(ProjectiveTransform, ProjectiveTransform)Compares two transformations for inequality.
operator *(ProjectiveTransform, ProjectiveTransform)Gets the transformation that applies a first one, then a second one.

operator ==(ProjectiveTransform, ProjectiveTransform)

ProjectiveTransform.cs

Compares two transformations for equality.

public static bool operator ==(ProjectiveTransform left, ProjectiveTransform right)

Parameters

left ProjectiveTransform
The first transformation.
right ProjectiveTransform
The second transformation.

Returns

bool true if every coefficient is equal; otherwise false.

implicit operator ProjectiveTransform(AffineTransform)

ProjectiveTransform.cs

Converts an affine transformation.

public static implicit operator ProjectiveTransform(AffineTransform transform)

Parameters

transform AffineTransform
The affine transformation.

Returns

ProjectiveTransform

operator !=(ProjectiveTransform, ProjectiveTransform)

ProjectiveTransform.cs

Compares two transformations for inequality.

public static bool operator !=(ProjectiveTransform left, ProjectiveTransform right)

Parameters

left ProjectiveTransform
The first transformation.
right ProjectiveTransform
The second transformation.

Returns

bool true if a coefficient differs; otherwise false.

operator *(ProjectiveTransform, ProjectiveTransform)

ProjectiveTransform.cs

Gets the transformation that applies a first one, then a second one.

public static ProjectiveTransform operator *(ProjectiveTransform left, ProjectiveTransform right)

Parameters

left ProjectiveTransform
The transformation applied first.
right ProjectiveTransform
The transformation applied to the result of the first one.

Returns

ProjectiveTransform The combined transformation.

Exceptions

ArgumentException
A coefficient of the result is not a finite number.