Class Matrix

Namespace: VectorDraw.Geometry

Assembly: VectorDraw.Geometry.dll

Represents a 4x4 homogeneous transformation matrix used for geometric calculations.

public class Matrix : BaseObject, IDisposable, IBaseObject, IVDSerialise, IFromString, ICloneable

Inheritance: object

BaseObject

BaseObject

Matrix

Implements: IDisposable

IBaseObject

IVDSerialise

IFromString

ICloneable

Inherited Members: BaseObject.Dispose()

BaseObject.Id

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetType()

object.MemberwiseClone()

Remarks

This class implements a full 4x4 transformation matrix using the internal fields named A00..A33.It supports common geometric operations such as translation, rotation, scaling, shearing, multiplication, inversion, point/vector transformation(including perspective via projectTransform), and conversion to 2D matrices for GDI+/Drawing2D usage.

The matrix layout used by this class is documented in the source(see vdraw formula): | A00 A01 A02 A03 | | A10 A11 A12 A13 | | A20 A21 A22 A23 | | A30 A31 A32 A33 | which corresponds to the internal vdmatrix fields a00..a33.Note that OpenGL uses a different memory ordering; the file's header documents that mapping.

UseprojectTransform(double, double, double) or projectTransform(gPoint) when the matrix may contain perspective(i.e.non-zero A30/A31/A32 or A33 != 1) since those methods divide by the computed homogeneous w.For pure affine transforms use the non-projecting Transform methods to avoid the divide step.

Mutating property setters and mutating operations call VectorDraw.Geometry.Matrix.UpdateMatrixProperties to reset cached matrix decomposition (exposed via MatrixProperties).

Constructors

Matrix(): Initializes the Matrix object.

Matrix(Matrix): Initializes the Matrix object from the given object.

Matrix(Quaternion): Initializes the Matrix object from the passed quaternion.

Matrix(gPoint, double, double): initializes the Matrix object from the given offset, rotation about Z axis in radians and scale.

Fields

Identity: Represents the canonical 4x4 identity transformation matrix. The identity matrix has ones on the main diagonal and zeros elsewhere and performs no transformation when applied to points or vectors.

Properties

A00: The 0,0 item of the matrix.

A01: The 0,1 item of the matrix.

A02: The 0,2 item of the matrix.

A03: The 0,3 item of the matrix.

A10: The 1,0 item of the matrix.

A11: The 1,1 item of the matrix.

A12: The 1,2 item of the matrix.

A13: The 1,3 item of the matrix.

A20: The 2,0 item of the matrix.

A21: The 2,1 item of the matrix.

A22: The 2,2 item of the matrix.

A23: The 2,3 item of the matrix.

A30: The 3,0 item of the matrix.

A31: The 3,1 item of the matrix.

A32: The 3,2 item of the matrix.

A33: The 3,3 item of the matrix.

IsNaN: Returns a boolean value indicating whether any of the object values evaluates to a value that is not a number (System.Double.NaN).

Offset: Gets or sets the translation offset (origin) stored in the matrix.

Properties: Gets the cached decomposition for this matrix as a MatrixProperties instance.

Xdir: Gets or sets the X axis direction vector stored in the matrix.

Ydir: Gets or sets the Y axis direction vector stored in the matrix.

ZExtrusion: Gets the signed length of the matrix Z direction (extrusion).

Zdir: Gets or sets the Z axis direction vector stored in the matrix.

Methods

ApplyECS2WCS(Vector): Builds an ECS->WCS basis that aligns the matrix Z axis with the supplied vector and post-multiplies it into this matrix. The method constructs orthonormal X/Y/Z axes (right-handed) from the provided Z direction and a computed X direction, fills a temporary matrix with those axis components and multiplies the result into the current matrix.

ApplyECS2WCS(Vector, Vector): Constructs a right-handed orthonormal basis from the supplied axes and post-multiplies it into this matrix. The method produces a local ECS->WCS matrix whose columns are the provided X, Y and Z axis components and multiplies the resulting matrix into the current matrix via Multiply(Matrix).

ApplyWCS2ECS(Vector): Applies the world-to-entity coordinate conversion by post-multiplying this matrix with the inverse of the matrix produced by ApplyECS2WCS(Vector) for the supplied Z axis.

As2dMatrix(): Converts this 4x4 transformation matrix into a 2D affine matrix representation.

Clone(): Create a new Matrix object as clone of this one.

CopyFrom(Matrix): Copies all items from the passed Matrix object to this.

DeSerialize(DeSerializer, string, object): This Function is called foreach field name of the Matrix object when opening in vdml format.

Determinant(): Calculates the determinant of the Matrix.

Equals(object): Checks if the passed object is equal to this object.

Equals(Matrix): Checks if the passed Matrix object is equal to this object.

FromString(string): Fills the Matrix with a passed string using the ToString format.

GetCompareHashCode(): Returns a 32-bit signed integer hash code for this object instance.

GetHashCode(): Returns a 32-bit signed integer hash code for this object instance.

GetInvertion(): Creates and returns a new Matrix that is the inverse of this matrix.

GetSystemMatrix(): Converts this Matrix into a 2D Matrix suitable for GDI+.

GetTransformVector(Vector, bool): Transforms the specified Vector by this matrix and returns the transformed coordinates.

GetWorldToViewProperties(out Vector, out double, out double, out double): Computes the camera/view direction and the three angles that define the matrix orientation.

IdentityMatrix(): Initializes this Matrix object as identity(A matrix with the main diagonal items equal to 1 and the rest 0).

Invert(): Inverts this matrix in-place.

IsEqualMatrix(Matrix, double): Check if the passed object's items are equal to this object's items taking into consideration the equality value.

IsUnitMatrix(): Checks if this MAtrix is equal to the Identity Matrix(the main diagonal items are equal to 1 and the rest 0).

Multiply(Matrix): Post-multiplies (composes) this matrix with the supplied matrix m2. The operation is equivalent to applying m2 first and then the current transform (this = this * m2).

OneUnitDY(): Get the y scale value of the matrix.

RotateAboutAxis(Vector, double): Rotate the Matrix by the passed angle in radians around a Vector direction.

RotateXMatrix(double): Rotate the Matrix by the passed angle in radians at the x direction.

RotateYMatrix(double): Rotate the Matrix by the passed angle in radians at the y direction.

RotateZMatrix(double): Rotate the Matrix by the passed angle in radians at the z direction.

ScaleMatrix(double, double, double): Applies scaling to this matrix using the specified X, Y and Z scale factors.

Serialize(Serializer): This Function is called when saving the Matrix object to vdml format.

SetFrom(gPoint, Vector, Vector): Configures this matrix from an origin point and two axis direction vectors. The method builds an orthonormal basis using xdir and ydir, sets the matrix axes (Xdir, Ydir, Zdir) and translation offset, then inverts the resulting matrix so the stored matrix represents the intended transform used by the rest of the library.

SetLookAt(gPoint, gPoint, double): Configures this matrix as a camera "look-at" view transform and then inverts it so the resulting matrix maps world coordinates into the camera/view space.

SetToViewAngles(double, double, double): Configures this matrix to represent a view transform defined by azimuth, tilt and twist angles.

SetToViewDirection(Vector, double): Configures this matrix to represent a view transform built from a view direction and a twist.

Shear(double, double): Applies an X/Y shear to this matrix.

TestOffsetSide(gPoint): Computes the signed offset of the specified point from the plane represented by this matrix.

ToString(): Gets a System.String that represents 16 values of the Matrix Object.

ToString(string): Gets a System.String that represents 16 values of the Matrix Object using the passed format.

ToString(Serializer): Sets the object's properties using a ToString string, according to the Serializer precision

Transform(double, double, double): Creates a point from the provided coordinates and returns a new point containing the result of transforming those coordinates by this matrix.

Transform(PointF[]): Transforms the supplied array of PointF in-place using this matrix.

Transform(Vertex): Transforms the specified Vertex by this matrix and returns a newly created transformed vertex.

Transform(Vertexes): Transforms all vertices in the supplied collection by this matrix.

Transform(Vertexes, bool): Transforms all vertices contained in the provided collection by this matrix. The transformation is applied in-place to each Vertex in the collection.

Transform(gPoint): Transforms the specified point by this matrix and returns the transformed coordinates.

Transform(gPoints): Transforms all gPoint objects contained in the supplied collection using this matrix. The transformation is applied in-place to each element of pts (each element is mutated).

Transform(gPoints, bool): Transforms the supplied collection of 3D gPoint instances using this matrix and returns a new collection with the transformed points.

Transform2GDIPoint(gPoint): Transforms the supplied 3D point to screen pixel coordinates.

TransformPt(gPoint, double, gPoint): Transforms the specified point by this matrix and stores the result in the provided target point. The value of thickness is added to pt.z before the transformation; this is commonly used to apply an extrusion/thickness offset when projecting geometry.

TransformPt(gPoint, gPoint): Transforms the provided source point using this matrix and stores the result in the destination point.

TransformPt2d(gPoint, double, gPoint): Transforms the specified point using this matrix and writes the resulting 2D coordinates into the provided destination point. The thickness value is added to the source point's Z component before transformation.

TransformPt2d(gPoint, gPoint): Transforms the specified source point using this matrix and writes the resulting projected coordinates into the provided destination point. If this matrix contains perspective components the result will be homogeneous-divided by the projection step performed by the called helper.

TransformRefPt(ref gPoint): Transforms the specified point by this matrix in-place.

TransformVector(Vector): Transforms the supplied Vector using the linear (direction) portion of this matrix and writes the result back into v. This overload normalizes the resulting vector to unit length after the transform.

TransformVector(Vector, bool): Transforms the supplied Vector using the linear (direction) portion of this matrix and writes the result back into v. The operation treats v as a direction vector (no translation) and therefore does not apply the matrix translation or perspective components.

TranslateMatrix(double, double, double): Translates the matrix by the specified distances along each axis.

TranslateMatrix(gPoint): Translates this matrix by the specified offset.

gPoints2GDIPOINTArray(gPoints): Projects the provided collection of 3D gPoint objects to screen pixel coordinates and returns them as an array of POINT.

gPoints2GDIPOINTArrayTrig(gPoints): Converts the passed collection of gPoint instances into an array of POINT suitable for drawing a solid polygon as a triangle-strip.

gPoints2POINTArray(gPoints): Projects the supplied collection of 3D gPoint instances to integer screen pixel coordinates and returns them as an array of Point.

gPoints2POINTArrayFloat(gPoints): Projects the supplied collection of 3D gPoint to screen coordinates and returns them as an array of PointF.

gPoints2POINTArrayTrig(gPoints): Converts the supplied collection of 3D gPoint values into an array of Point suitable for drawing a solid polygon using a triangle-strip order.

gPoints2POINTArrayTrigFloat(gPoints): Converts the supplied collection of 3D gPoint instances into an array of PointF suitable for drawing a solid polygon using triangle-strip ordering.

projectTransform(double, double, double): Creates a new gPoint from the supplied coordinates and transforms it by this matrix, performing a homogeneous (perspective) divide if the matrix contains perspective components.

projectTransform(gPoint): Transforms the specified gPoint by this matrix and returns a new transformed point. If the matrix contains perspective components the result is homogeneous-divided (projected) before being returned.

projectTransform(gPoints): Transforms all gPoint objects contained in the supplied collection using this matrix and writes the projected results back into the same collection. The projection performed is homogeneous: when the matrix contains perspective components the coordinates are divided by the computed homogeneous w.

projectTransform(gPoints, bool): Transforms the supplied collection of 3D gPoint instances using homogeneous projection and returns a new collection containing the transformed points.

projectTransform_ref(double, double, double, ref gPoint): Transforms the supplied coordinates by this matrix and stores the result into the provided gPoint reference. The method performs a homogeneous (perspective) divide when the matrix contains perspective components.

Operators

operator ==(Matrix, Matrix): Implements the == operator for two Matrix objects.

operator !=(Matrix, Matrix): Implements the != operator for two Matrix objects.

operator *(Matrix, Matrix): Multiplies two Matrix instances and returns a new Matrix representing the composition of the transforms (equivalent to applying m2 then m1 when transforming points).

Table of Contents