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

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.

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

Gets the transformation that changes nothing.

public static ProjectiveTransform Identity { get; }

Property value

ProjectiveTransform

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

Gets a value indicating whether the transformation changes nothing.

public bool IsIdentity { get; }

Property value

bool

Gets the factor of x in X.

public double M11 { get; }

Property value

double

Gets the factor of x in Y.

public double M12 { get; }

Property value

double

Gets the factor of x in W.

public double M13 { get; }

Property value

double

Gets the factor of y in X.

public double M21 { get; }

Property value

double

Gets the factor of y in Y.

public double M22 { get; }

Property value

double

Gets the factor of y in W.

public double M23 { get; }

Property value

double

Gets the constant of X.

public double M31 { get; }

Property value

double

Gets the constant of Y.

public double M32 { get; }

Property value

double

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.
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.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.

EstimateHomography(ReadOnlySpan<PointD>, ReadOnlySpan<PointD>)

ProjectiveTransform.Estimation.cs

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.

public static ProjectiveTransform EstimateHomography(ReadOnlySpan<PointD> source, ReadOnlySpan<PointD> destination)

Parameters

source ReadOnlySpan<PointD>
The source points.
destination ReadOnlySpan<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.cs

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.

public static HomographyEstimate EstimateHomographyRobust(ReadOnlySpan<PointD> source, ReadOnlySpan<PointD> destination, HomographyRansacOptions? options = null)

Parameters

source ReadOnlySpan<PointD>
The source points.
destination ReadOnlySpan<PointD>
The destination points, in the same order.
options HomographyRansacOptions?
The threshold, the number of samples and the seed, or null for HomographyRansacOptions.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);
}

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.

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.

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.