ProjectiveTransform Struct
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
| Name | Description |
|---|---|
| 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.csInitializes 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
m11double- The factor of x in X.
m12double- The factor of x in Y.
m13double- The factor of x in W.
m21double- The factor of y in X.
m22double- The factor of y in Y.
m23double- The factor of y in W.
m31double- The constant of X: the horizontal translation of an affine transformation.
m32double- The constant of Y: the vertical translation of an affine transformation.
m33double- The constant of W.
Exceptions
ArgumentException- A coefficient is not a finite number.
Properties
| Name | Description |
|---|---|
| Determinant | Gets the determinant of the nine coefficients: zero when the transformation flattens the plane to a line or a point. |
| Identity | Gets the transformation that changes nothing. |
| IsAffine | 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. |
| IsIdentity | Gets a value indicating whether the transformation changes nothing. |
| M11 | Gets the factor of x in X. |
| M12 | Gets the factor of x in Y. |
| M13 | Gets the factor of x in W. |
| M21 | Gets the factor of y in X. |
| M22 | Gets the factor of y in Y. |
| M23 | Gets the factor of y in W. |
| M31 | Gets the constant of X. |
| M32 | Gets the constant of Y. |
| M33 | Gets the constant of W. |
Determinant
ProjectiveTransform.csIdentity
ProjectiveTransform.csGets the transformation that changes nothing.
public static ProjectiveTransform Identity { get; }Property value
IsAffine
ProjectiveTransform.csIsIdentity
ProjectiveTransform.csMethods
| Name | Description |
|---|---|
| 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. |
| EstimateHomography(ReadOnlySpan<PointD>, ReadOnlySpan<PointD>) | Estimates the homography that maps each source point onto its destination point, by least squares: the projective transformation of a plane seen from two points of view, such as the corners of a document matched in two photos. |
| EstimateHomographyRobust(ReadOnlySpan<PointD>, ReadOnlySpan<PointD>, HomographyRansacOptions?) | Estimates the homography that maps the source points onto their destination points when some of the correspondences are wrong, such as the corners matched between two photos: RANSAC keeps the homography that the most correspondences agree on, and refits it on them. |
| 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.csCreates 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
sourceRectangleD- The rectangle. Must not be empty.
topLeftPointD- Where the top-left corner of the rectangle goes.
topRightPointD- Where the top-right corner goes.
bottomRightPointD- Where the bottom-right corner goes.
bottomLeftPointD- 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.csIndicates whether the current object is equal to another object of the same type.
public bool Equals(ProjectiveTransform other)Parameters
otherProjectiveTransform- 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.csEstimateHomography(ReadOnlySpan<PointD>, ReadOnlySpan<PointD>)
ProjectiveTransform.Estimation.csEstimates the homography that maps each source point onto its destination point, by least squares: the projective transformation of a plane seen from two points of view, such as the corners of a document matched in two photos.
public static ProjectiveTransform EstimateHomography(ReadOnlySpan<PointD> source, ReadOnlySpan<PointD> destination)Parameters
sourceReadOnlySpan<PointD>- The source points.
destinationReadOnlySpan<PointD>- The destination points, in the same order.
Returns
ProjectiveTransform The homography.
Exceptions
ArgumentException- The spans do not have the same length, have fewer than four points, hold a coordinate that is not finite, or the points determine no homography (too many of them on a line).
Remarks
The method is the normalized direct linear transformation (Hartley and Zisserman, algorithm 4.2): the points are centered and scaled, and the homography minimizes the algebraic error of the equations of all the correspondences. Four correspondences, no three of their points on a line, give the exact homography; more correspondences are averaged, and all of them count: when some are wrong, use ProjectiveTransform.EstimateHomographyRobust.
The result is scaled so that W is 1 at the centroid of the source points (they are in front of the viewer). It is computed with additions, multiplications, divisions and square roots only, so it does not depend on the platform. Pass it to ImageProcessingExtensions.Transform to warp an image, with TransformCanvasMode.Explicit to choose the canvas of the destination points.
Example
[Fact]
public void EstimateHomography_FromCorrespondences()
{
// The corners of a page found in a photo, and where they go: an upright 210x297 page
PointD[] photo = [new(31, 18), new(240, 42), new(225, 330), new(12, 300)];
PointD[] page = [new(0, 0), new(210, 0), new(210, 297), new(0, 297)];
var homography = ProjectiveTransform.EstimateHomography(photo, page);
// Four correspondences give the exact homography: each corner lands on its destination
for (var i = 0; i < 4; i++)
{
Assert.True(homography.TryTransform(photo[i], out var point));
Assert.InRange(point.DistanceTo(page[i]), 0, 1e-9);
}
// Warping the photo onto a 210x297 canvas with it gives the four-point perspective correction
using var image = new Image<Rgb24>(256, 340);
for (var y = 0; y < 340; y++)
{
for (var x = 0; x < 256; x++)
{
image.Frames[0][x, y] = new Rgb24((byte)x, (byte)(y / 2), 100);
}
}
var background = new Rgba64(65535, 65535, 65535, 65535);
using var corrected = image.Clone();
corrected.CorrectPerspective(photo[0], photo[1], photo[2], photo[3], new Size(210, 297), new TransformOptions { BackgroundColor = background });
image.Transform(homography, new TransformOptions { CanvasMode = TransformCanvasMode.Explicit, CanvasSize = new Size(210, 297), BackgroundColor = background });
Assert.Equal(new Size(210, 297), image.Size);
for (var y = 0; y < 297; y++)
{
for (var x = 0; x < 210; x++)
{
Assert.InRange(Math.Abs(image.Frames[0][x, y].R - corrected.Frames[0][x, y].R), 0, 1);
Assert.InRange(Math.Abs(image.Frames[0][x, y].G - corrected.Frames[0][x, y].G), 0, 1);
}
}
}EstimateHomographyRobust(ReadOnlySpan<PointD>, ReadOnlySpan<PointD>, HomographyRansacOptions?)
ProjectiveTransform.Estimation.csEstimates the homography that maps the source points onto their destination points when some of the correspondences are wrong, such as the corners matched between two photos: RANSAC keeps the homography that the most correspondences agree on, and refits it on them.
public static HomographyEstimate EstimateHomographyRobust(ReadOnlySpan<PointD> source, ReadOnlySpan<PointD> destination, HomographyRansacOptions? options = null)Parameters
sourceReadOnlySpan<PointD>- The source points.
destinationReadOnlySpan<PointD>- The destination points, in the same order.
optionsHomographyRansacOptions?- The threshold, the number of samples and the seed, or
nullforHomographyRansacOptions.Default.
Returns
HomographyEstimate The homography, its inliers and their error.
Exceptions
ArgumentException- The spans do not have the same length, have fewer than four points, hold a coordinate that is not finite, or no sample determines a homography.
Remarks
The method is RANSAC (Fischler and Bolles, 1981): HomographyRansacOptions.Iterations samples of four correspondences are drawn with a generator seeded by HomographyRansacOptions.Seed, and the exact homography of each sample is scored by its inliers, the correspondences whose source point lands within HomographyRansacOptions.Threshold of its destination. The homography with the most inliers (then the smallest sum of their squared errors, then the first one) is refitted by least squares on its inliers (ProjectiveTransform.EstimateHomography), and the refit is kept when it has at least as many inliers. The same points and options give the same result on every platform.
Example
[Fact]
public void EstimateHomographyRobust_IgnoreTheOutliers()
{
// 20 corners matched between two photos of a poster, and 5 wrong matches
var truth = ProjectiveTransform.CreateFromQuadrilateral(new RectangleD(0, 0, 100, 100), new PointD(10, 12), new PointD(118, 5), new PointD(125, 110), new PointD(4, 98));
var source = new List<PointD>();
var destination = new List<PointD>();
for (var i = 0; i < 20; i++)
{
var point = new PointD(5 + (i * 37 % 90), 3 + (i * 53 % 94));
Assert.True(truth.TryTransform(point, out var image));
source.Add(point);
destination.Add(image);
}
for (var i = 0; i < 5; i++)
{
source.Add(new PointD(20 + (i * 15), 50));
destination.Add(new PointD(200 - (i * 31), 10 + (i * 40)));
}
// RANSAC keeps the homography the 20 good matches agree on
var estimate = ProjectiveTransform.EstimateHomographyRobust([.. source], [.. destination]);
Assert.Equal(20, estimate.InlierCount);
Assert.All(Enumerable.Range(0, 25), i => Assert.Equal(i < 20, estimate.Inliers[i]));
Assert.InRange(estimate.RootMeanSquareError, 0, 1e-6);
}GetHashCode()
ProjectiveTransform.csMultiply(ProjectiveTransform, ProjectiveTransform)
ProjectiveTransform.csGets the transformation that applies a first one, then a second one.
public static ProjectiveTransform Multiply(ProjectiveTransform first, ProjectiveTransform second)Parameters
firstProjectiveTransform- The transformation applied first.
secondProjectiveTransform- 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.csGets the transformation that applies this one first, then another one.
public ProjectiveTransform Then(ProjectiveTransform next)Parameters
nextProjectiveTransform- 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.csTryInvert(ProjectiveTransform)
ProjectiveTransform.csGets the transformation that undoes this one.
public bool TryInvert(out ProjectiveTransform inverse)Parameters
inverseProjectiveTransform- 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.csOperators
| Name | Description |
|---|---|
| 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.csCompares two transformations for equality.
public static bool operator ==(ProjectiveTransform left, ProjectiveTransform right)Parameters
leftProjectiveTransform- The first transformation.
rightProjectiveTransform- The second transformation.
Returns
bool true if every coefficient is equal; otherwise false.
implicit operator ProjectiveTransform(AffineTransform)
ProjectiveTransform.csConverts an affine transformation.
public static implicit operator ProjectiveTransform(AffineTransform transform)operator !=(ProjectiveTransform, ProjectiveTransform)
ProjectiveTransform.csCompares two transformations for inequality.
public static bool operator !=(ProjectiveTransform left, ProjectiveTransform right)Parameters
leftProjectiveTransform- The first transformation.
rightProjectiveTransform- The second transformation.
Returns
bool true if a coefficient differs; otherwise false.
operator *(ProjectiveTransform, ProjectiveTransform)
ProjectiveTransform.csGets the transformation that applies a first one, then a second one.
public static ProjectiveTransform operator *(ProjectiveTransform left, ProjectiveTransform right)Parameters
leftProjectiveTransform- The transformation applied first.
rightProjectiveTransform- 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.