Struct Homography

Namespace

Egami.Operations

Assembly

Egami.dll

A 3 × 3 projective matrix in double precision, for perspective transforms. It follows Matrix3x2's conventions: points are row vectors, so [x, y, 1] × H = [X, Y, W] and the point lands at (X / W, Y / W); A * B applies A first, then B. Coordinates are in pixels with the origin at the top-left corner of the top-left pixel, so pixel centers sit at +0.5.

public readonly struct Homography : IEquatable<Homography>

Implements

IEquatable<Homography>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Examples

// The four corners of a page photographed at an angle, top-left first and clockwise...
Vector2[] corners = [new(120, 60), new(560, 40), new(600, 430), new(80, 420)];

// ...go to the corners of an upright 420 × 594 (A4-shaped) canvas.
Homography straighten = Homography.FromQuad(corners, new Rect(0, 0, 420, 594));
using Raster page = photo.Derive(ops => ops.Transform(straighten, new TransformOptions { Viewport = new Rect(0, 0, 420, 594) }), Ct);

// Homography maps points too, and inverts.
Vector2 middle = straighten.Map(new Vector2(340, 240));
bool invertible = straighten.TryInvert(out Homography back);

Remarks

default(Homography) is all zeros, which maps nothing; start from Identity or a factory.

Constructors

Homography(double, double, double, double, double, double, double, double, double)

Initializes a new instance of the Homography struct from its nine elements, row by row.

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

Parameters

m11 double

Row 1, column 1: x's weight in X.

m12 double

Row 1, column 2: x's weight in Y.

m13 double

Row 1, column 3: x's weight in W.

m21 double

Row 2, column 1: y's weight in X.

m22 double

Row 2, column 2: y's weight in Y.

m23 double

Row 2, column 3: y's weight in W.

m31 double

Row 3, column 1: the X translation.

m32 double

Row 3, column 2: the Y translation.

m33 double

Row 3, column 3: the W constant, 1 for an affine matrix.

Properties

Determinant

Gets the determinant. A matrix whose determinant is 0 cannot be inverted and collapses the image.

public double Determinant { get; }

Property Value

double

Identity

Gets the matrix that maps every point to itself.

public static Homography Identity { get; }

Property Value

Homography

IsAffine

Gets a value indicating whether the matrix has no perspective: its third column is (0, 0, c) with c ≠ 0.

public bool IsAffine { get; }

Property Value

bool

IsIdentity

Gets a value indicating whether the matrix maps every point to itself.

public bool IsIdentity { get; }

Property Value

bool

M11

Gets row 1, column 1.

public double M11 { get; }

Property Value

double

M12

Gets row 1, column 2.

public double M12 { get; }

Property Value

double

M13

Gets row 1, column 3.

public double M13 { get; }

Property Value

double

M21

Gets row 2, column 1.

public double M21 { get; }

Property Value

double

M22

Gets row 2, column 2.

public double M22 { get; }

Property Value

double

M23

Gets row 2, column 3.

public double M23 { get; }

Property Value

double

M31

Gets row 3, column 1.

public double M31 { get; }

Property Value

double

M32

Gets row 3, column 2.

public double M32 { get; }

Property Value

double

M33

Gets row 3, column 3.

public double M33 { get; }

Property Value

double

Methods

CreateRotation(double)

Returns a rotation about the origin, clockwise on screen for a positive angle, as CreateRotation(float).

public static Homography CreateRotation(double radians)

Parameters

radians double

The angle in radians.

Returns

Homography

The rotation.

CreateRotation(double, Vector2)

Returns a rotation about center, clockwise on screen for a positive angle.

public static Homography CreateRotation(double radians, Vector2 center)

Parameters

radians double

The angle in radians.

center Vector2

The point that stays put.

Returns

Homography

The rotation.

CreateScale(double, double)

Returns a scale about the origin.

public static Homography CreateScale(double scaleX, double scaleY)

Parameters

scaleX double

The horizontal factor; negative mirrors.

scaleY double

The vertical factor; negative mirrors.

Returns

Homography

The scale.

CreateScale(double, double, Vector2)

Returns a scale about center.

public static Homography CreateScale(double scaleX, double scaleY, Vector2 center)

Parameters

scaleX double

The horizontal factor; negative mirrors.

scaleY double

The vertical factor; negative mirrors.

center Vector2

The point that stays put.

Returns

Homography

The scale.

CreateSkew(double, double)

Returns a shear about the origin, as CreateSkew(float, float): x moves by y × tan(radiansX) and y by x × tan(radiansY).

public static Homography CreateSkew(double radiansX, double radiansY)

Parameters

radiansX double

The angle the vertical lines lean by, in radians.

radiansY double

The angle the horizontal lines lean by, in radians.

Returns

Homography

The shear.

CreateSkew(double, double, Vector2)

Returns a shear about center.

public static Homography CreateSkew(double radiansX, double radiansY, Vector2 center)

Parameters

radiansX double

The angle the vertical lines lean by, in radians.

radiansY double

The angle the horizontal lines lean by, in radians.

center Vector2

The point that stays put.

Returns

Homography

The shear.

CreateTranslation(double, double)

Returns a translation.

public static Homography CreateTranslation(double x, double y)

Parameters

x double

The horizontal move, in pixels.

y double

The vertical move, in pixels.

Returns

Homography

The translation.

Equals(Homography)

Returns whether two matrices have the same elements.

public bool Equals(Homography other)

Parameters

other Homography

The other matrix.

Returns

bool

true if every element is equal.

Equals(object?)

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.

FromAffine(Matrix3x2)

Returns the matrix of an affine Matrix3x2.

public static Homography FromAffine(Matrix3x2 matrix)

Parameters

matrix Matrix3x2

The affine matrix.

Returns

Homography

The same mapping as a homography.

FromMatrix4x4(Matrix4x4)

Returns the projection of a 3D matrix applied to the image's plane at z = 0, as CSS matrix3d and Skia's SkM44 draw a flat image: [x, y, 0, 1] × M = [X, Y, Z, W] lands at (X / W, Y / W).

public static Homography FromMatrix4x4(Matrix4x4 matrix)

Parameters

matrix Matrix4x4

The 3D matrix, in Matrix4x4's row-vector convention.

Returns

Homography

The homography that maps the plane the same way.

FromQuad(Rect, ReadOnlySpan<Vector2>)

Returns the matrix that moves the corners of a rectangle onto four points, in the order top-left, top-right, bottom-right, bottom-left.

public static Homography FromQuad(Rect source, ReadOnlySpan<Vector2> destination)

Parameters

source Rect

The rectangle, in pixels; its corners are its pixel edges.

destination ReadOnlySpan<Vector2>

The four points, in that order.

Returns

Homography

The homography.

Exceptions

ArgumentException

destination does not hold exactly four finite points, three of them lie on one line, or the rectangle is empty.

FromQuad(ReadOnlySpan<Vector2>, Rect)

Returns the matrix that moves four points onto the corners of a rectangle, in the order top-left, top-right, bottom-right, bottom-left: what straightening a photographed page needs.

public static Homography FromQuad(ReadOnlySpan<Vector2> source, Rect destination)

Parameters

source ReadOnlySpan<Vector2>

The four points, in that order.

destination Rect

The rectangle, in pixels; its corners are its pixel edges.

Returns

Homography

The homography.

Exceptions

ArgumentException

source does not hold exactly four finite points, three of them lie on one line, or the rectangle is empty.

FromQuad(ReadOnlySpan<Vector2>, ReadOnlySpan<Vector2>)

Returns the matrix that moves four points onto four others: corner i of source lands on corner i of destination. Give the corners in the same order on both sides, for example top-left, top-right, bottom-right, bottom-left.

public static Homography FromQuad(ReadOnlySpan<Vector2> source, ReadOnlySpan<Vector2> destination)

Parameters

source ReadOnlySpan<Vector2>

Four points, no three on one line.

destination ReadOnlySpan<Vector2>

The four points they go to, no three on one line.

Returns

Homography

The homography.

Exceptions

ArgumentException

A span does not hold exactly four finite points, or three of them lie on one line.

GetHashCode()

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.

Map(Vector2)

Maps a point.

public Vector2 Map(Vector2 point)

Parameters

point Vector2

The point, in pixels.

Returns

Vector2

Where it lands; both coordinates are NaN when the point goes to infinity (W = 0).

Multiply(Homography, Homography)

Returns the matrix that applies first, then second.

public static Homography Multiply(Homography first, Homography second)

Parameters

first Homography

The matrix applied first.

second Homography

The matrix applied second.

Returns

Homography

The product.

ToString()

Returns the elements row by row, as { {M11 M12 M13} {M21 M22 M23} {M31 M32 M33} }.

public override string ToString()

Returns

string

The text.

TryInvert(out Homography)

Returns the inverse, which maps destination points back to source points.

public bool TryInvert(out Homography inverse)

Parameters

inverse Homography

The inverse, or the zero matrix when there is none.

Returns

bool

false if the matrix is singular (or not finite) and has no inverse.

Operators

operator ==(Homography, Homography)

Returns whether two matrices have the same elements.

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

Parameters

left Homography

The first matrix.

right Homography

The second matrix.

Returns

bool

true if every element is equal.

operator !=(Homography, Homography)

Returns whether two matrices differ in any element.

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

Parameters

left Homography

The first matrix.

right Homography

The second matrix.

Returns

bool

true if any element differs.

operator *(Homography, Homography)

Returns the matrix that applies first, then second.

public static Homography operator *(Homography first, Homography second)

Parameters

first Homography

The matrix applied first.

second Homography

The matrix applied second.

Returns

Homography

The product.