Meziantou.Framework

Transform3D Struct

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

A transformation of space, as the 4x4 matrices of CSS transforms: translations, scalings and rotations in three dimensions, and perspective. A drawing is the plane z = 0; Transform3D.ToProjectiveTransform gives what the transformation does to it.

public readonly struct Transform3D : IEquatable<Transform3D>

Remarks

A point (x, y, z) becomes (X / W, Y / W, Z / W), with X = x M11 + y M21 + z M31 + M41, Y = x M12 + y M22 + z M32 + M42, Z = x M13 + y M23 + z M33 + M43 and W = x M14 + y M24 + z M34 + M44: the coefficients have the names of the DOMMatrix of the web platform, and of AffineTransform in two dimensions. The default value is the identity.

The coordinate system is the one of the canvas and of CSS: x to the right, y downward, z toward the viewer. Angles are in degrees and their sines and cosines come from additions, multiplications and divisions only, as for AffineTransform: a rotation by a multiple of 90 degrees is exact.

Transformations are combined in three dimensions (Transform3D.Then), so that what one of them does to z reaches the next one: a rotation around the y axis, then a perspective, shows the side of the plane that comes closer larger. Inside DrawingCanvas.Transform, a transformation of a callback started inside another one is combined that way too.

Implements

Constructors

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

Transform3D(double, double, double, double, double, double, double, double, double, double, double, double, double, double, double, double)

Transform3D.cs

Initializes a new instance of the Transform3D struct from its coefficients, row by row.

public Transform3D(double m11, double m12, double m13, double m14, double m21, double m22, double m23, double m24, double m31, double m32, double m33, double m34, double m41, double m42, double m43, double m44)

Parameters

m11 double
The factor of x in X.
m12 double
The factor of x in Y.
m13 double
The factor of x in Z.
m14 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 Z.
m24 double
The factor of y in W.
m31 double
The factor of z in X.
m32 double
The factor of z in Y.
m33 double
The factor of z in Z.
m34 double
The factor of z in W.
m41 double
The constant of X: the translation along x.
m42 double
The constant of Y: the translation along y.
m43 double
The constant of Z: the translation along z.
m44 double
The constant of W.

Exceptions

ArgumentException
A coefficient is not a finite number.

Properties

NameDescription
IdentityGets the transformation that changes nothing.
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 Z.
M14Gets 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 Z.
M24Gets the factor of y in W.
M31Gets the factor of z in X.
M32Gets the factor of z in Y.
M33Gets the factor of z in Z.
M34Gets the factor of z in W.
M41Gets the constant of X: the translation along x.
M42Gets the constant of Y: the translation along y.
M43Gets the constant of Z: the translation along z.
M44Gets the constant of W.

Identity

Transform3D.cs

Gets the transformation that changes nothing.

public static Transform3D Identity { get; }

Property value

Transform3D

IsIdentity

Transform3D.cs

Gets a value indicating whether the transformation changes nothing.

public bool IsIdentity { get; }

Property value

bool

M11

Transform3D.cs

Gets the factor of x in X.

public double M11 { get; }

Property value

double

M12

Transform3D.cs

Gets the factor of x in Y.

public double M12 { get; }

Property value

double

M13

Transform3D.cs

Gets the factor of x in Z.

public double M13 { get; }

Property value

double

M14

Transform3D.cs

Gets the factor of x in W.

public double M14 { get; }

Property value

double

M21

Transform3D.cs

Gets the factor of y in X.

public double M21 { get; }

Property value

double

M22

Transform3D.cs

Gets the factor of y in Y.

public double M22 { get; }

Property value

double

M23

Transform3D.cs

Gets the factor of y in Z.

public double M23 { get; }

Property value

double

M24

Transform3D.cs

Gets the factor of y in W.

public double M24 { get; }

Property value

double

M31

Transform3D.cs

Gets the factor of z in X.

public double M31 { get; }

Property value

double

M32

Transform3D.cs

Gets the factor of z in Y.

public double M32 { get; }

Property value

double

M33

Transform3D.cs

Gets the factor of z in Z.

public double M33 { get; }

Property value

double

M34

Transform3D.cs

Gets the factor of z in W.

public double M34 { get; }

Property value

double

M41

Transform3D.cs

Gets the constant of X: the translation along x.

public double M41 { get; }

Property value

double

M42

Transform3D.cs

Gets the constant of Y: the translation along y.

public double M42 { get; }

Property value

double

M43

Transform3D.cs

Gets the constant of Z: the translation along z.

public double M43 { get; }

Property value

double

M44

Transform3D.cs

Gets the constant of W.

public double M44 { get; }

Property value

double

Methods

NameDescription
CreatePerspective(double)Creates a perspective, as perspective of CSS: the viewer is at a distance from the plane z = 0, on the z axis.
CreateRotation(double, double, double, double)Creates a rotation around an axis through the origin, as rotate3d of CSS.
CreateRotationX(double)Creates a rotation around the x axis, as rotateX of CSS.
CreateRotationY(double)Creates a rotation around the y axis, as rotateY of CSS.
CreateRotationZ(double)Creates a rotation around the z axis, as rotateZ of CSS: the rotation of AffineTransform.CreateRotation.
CreateScale(double, double, double)Creates a scaling around the origin.
CreateTranslation(double, double, double)Creates a translation.
Equals(Transform3D)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(Transform3D, Transform3D)Gets the transformation that applies a first one, then a second one.
Then(Transform3D)Gets the transformation that applies this one first, then another one.
ToProjectiveTransform()Gets what the transformation does to the plane z = 0, seen from the viewer: the point (x, y) becomes ((x M11 + y M21 + M41) / W, (x M12 + y M22 + M42) / W) with W = x M14 + y M24 + M44.
ToString()Returns the coefficients row by row, formatted as [M11 M12 ... M44].

CreatePerspective(double)

Transform3D.cs

Creates a perspective, as perspective of CSS: the viewer is at a distance from the plane z = 0, on the z axis.

public static Transform3D CreatePerspective(double distance)

Parameters

distance double
The distance from the viewer to the plane z = 0, in pixels. Must be positive.

Returns

Transform3D The transformation: what comes closer to the viewer is larger, and what reaches the viewer has no image.

Exceptions

ArgumentOutOfRangeException
distance is not a positive finite number.

CreateRotation(double, double, double, double)

Transform3D.cs

Creates a rotation around an axis through the origin, as rotate3d of CSS.

public static Transform3D CreateRotation(double axisX, double axisY, double axisZ, double degrees)

Parameters

axisX double
The x component of the direction of the axis.
axisY double
The y component of the direction of the axis.
axisZ double
The z component of the direction of the axis.
degrees double
The angle, in degrees, clockwise when the axis points toward the viewer.

Returns

Transform3D The transformation; the identity when the direction has no length.

Exceptions

ArgumentException
A component of the axis, or degrees, is not a finite number.

CreateRotationX(double)

Transform3D.cs

Creates a rotation around the x axis, as rotateX of CSS.

public static Transform3D CreateRotationX(double degrees)

Parameters

degrees double
The angle, in degrees: a positive angle brings the bottom of the plane toward the viewer.

Returns

Transform3D The transformation.

Exceptions

ArgumentException
degrees is not a finite number.

CreateRotationY(double)

Transform3D.cs

Creates a rotation around the y axis, as rotateY of CSS.

public static Transform3D CreateRotationY(double degrees)

Parameters

degrees double
The angle, in degrees: a positive angle moves the right of the plane away from the viewer.

Returns

Transform3D The transformation.

Exceptions

ArgumentException
degrees is not a finite number.

CreateRotationZ(double)

Transform3D.cs

Creates a rotation around the z axis, as rotateZ of CSS: the rotation of AffineTransform.CreateRotation.

public static Transform3D CreateRotationZ(double degrees)

Parameters

degrees double
The angle, in degrees. A positive angle turns clockwise on the image.

Returns

Transform3D The transformation.

Exceptions

ArgumentException
degrees is not a finite number.

CreateScale(double, double, double)

Transform3D.cs

Creates a scaling around the origin.

public static Transform3D CreateScale(double x, double y, double z)

Parameters

x double
The factor along x.
y double
The factor along y.
z double
The factor along z.

Returns

Transform3D The transformation.

Exceptions

ArgumentException
A factor is not a finite number.

CreateTranslation(double, double, double)

Transform3D.cs

Creates a translation.

public static Transform3D CreateTranslation(double x, double y, double z)

Parameters

x double
The distance along x.
y double
The distance along y.
z double
The distance along z, toward the viewer when positive.

Returns

Transform3D The transformation.

Exceptions

ArgumentException
A distance is not a finite number.

Equals overloads

Equals(Transform3D)

Transform3D.cs

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

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

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

Equals(object?)

Transform3D.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()

Transform3D.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(Transform3D, Transform3D)

Transform3D.cs

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

public static Transform3D Multiply(Transform3D first, Transform3D second)

Parameters

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

Returns

Transform3D The combined transformation.

Exceptions

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

Then(Transform3D)

Transform3D.cs

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

public Transform3D Then(Transform3D next)

Parameters

next Transform3D
The transformation applied after this one.

Returns

Transform3D The combined transformation.

Exceptions

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

ToProjectiveTransform()

Transform3D.cs

Gets what the transformation does to the plane z = 0, seen from the viewer: the point (x, y) becomes ((x M11 + y M21 + M41) / W, (x M12 + y M22 + M42) / W) with W = x M14 + y M24 + M44.

public ProjectiveTransform ToProjectiveTransform()

Returns

ProjectiveTransform The projective transformation of the plane.

ToString()

Transform3D.cs

Returns the coefficients row by row, formatted as [M11 M12 ... M44].

public override string ToString()

Returns

string A string representation of the transformation.

Operators

NameDescription
operator ==(Transform3D, Transform3D)Compares two transformations for equality.
implicit operator Transform3D(AffineTransform)Converts a transformation of the plane: it moves the points of each plane z = constant in that plane.
implicit operator Transform3D(ProjectiveTransform)Converts a projective transformation of the plane: z is kept, and divided by W as x and y are.
operator !=(Transform3D, Transform3D)Compares two transformations for inequality.
operator *(Transform3D, Transform3D)Gets the transformation that applies a first one, then a second one.

operator ==(Transform3D, Transform3D)

Transform3D.cs

Compares two transformations for equality.

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

Parameters

left Transform3D
The first transformation.
right Transform3D
The second transformation.

Returns

bool true if every coefficient is equal; otherwise false.

op_Implicit overloads

implicit operator Transform3D(AffineTransform)

Transform3D.cs

Converts a transformation of the plane: it moves the points of each plane z = constant in that plane.

public static implicit operator Transform3D(AffineTransform transform)
Parameters
transform AffineTransform
The transformation of the plane.
Returns

Transform3D

implicit operator Transform3D(ProjectiveTransform)

Transform3D.cs

Converts a projective transformation of the plane: z is kept, and divided by W as x and y are.

public static implicit operator Transform3D(ProjectiveTransform transform)
Parameters
transform ProjectiveTransform
The transformation of the plane.
Returns

Transform3D

operator !=(Transform3D, Transform3D)

Transform3D.cs

Compares two transformations for inequality.

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

Parameters

left Transform3D
The first transformation.
right Transform3D
The second transformation.

Returns

bool true if a coefficient differs; otherwise false.

operator *(Transform3D, Transform3D)

Transform3D.cs

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

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

Parameters

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

Returns

Transform3D The combined transformation.

Exceptions

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