Show / Hide Table of Contents

# Class Matrix2D

2D Matrix

A Matrix2D object represents a 3x3 matrix that, in turn, represents an affine transformation. A Matrix2D object stores only six of the nine numbers in a 3x3 matrix because all 3x3 matrices that represent affine transformations have the same third column (0, 0, 1).

Affine transformations include rotating, scaling, reflecting, shearing, and translating. In PDFNet, the Matrix2D class provides the foundation for performing affine transformations on vector drawings, images, and text.

A transformation matrix specifies the relationship between two coordinate spaces. By modifying a transformation matrix, objects can be scaled, rotated, translated, or transformed in other ways.

A transformation matrix in PDF is specified by six numbers, usually in the form of an array containing six elements. In its most general form, this array is denoted [a b c d h v]; The following table lists the arrays that specify the most common transformations:

- Translations are specified as [1 0 0 1 tx ty], where tx and ty are the distances to translate the origin of the coordinate system in the horizontal and vertical dimensions, respectively.
- Scaling is obtained by [sx 0 0 sy 0 0]. This scales the coordinates so that 1 unit in the horizontal and vertical dimensions of the new coordinate system is the same size as sx and sy units, respectively, in the previous coordinate system.
- Rotations are produced by [cos(A) sin(A) -sin(A) cos(A) 0 0], which has the effect of rotating the coordinate system axes by an angle 'A' counterclockwise.
- Skew is specified by [1 tan(A) tan(B) 1 0 0], which skews the x axis by an angle A and the y axis by an angle B.

Matrix2D elements are positioned as follows :

| m_a m_b 0 | | m_c m_d 0 | | m_h m_v 1 |

A single Matrix2D object can store a single transformation or a sequence of transformations. The latter is called a composite transformation. The matrix of a composite transformation is obtained by multiplying (concatenating) the matrices of the individual transformations. Because matrix multiplication is not commutative-the order in which matrices are multiplied is significant. For example, if you first rotate, then scale, then translate, you get a different result than if you first translate, then rotate, then scale.

For more information on properties of PDF matrices please refer to PDF Reference Manual (Sections 4.2 'Coordinate Systems' and 4.2.3 'Transformation Matrices')

The following sample illustrates how to use Matrix2D in order to position an image on the page. Note that PDFNet uses the same convention of matrix multiplication used in PostScript and OpenGL.

    Element element = eb.CreateImage(Image(...));
    double deg2rad = 3.1415926535 / 180.0;
    Matrix2D mtx = Matrix2D(1, 0, 0, 1, 0, 200); // Translate
    mtx.multiply(Matrix2D(300, 0, 0, 200, 0, 0));    // Scale
    mtx.multiply(Matrix2D.RotationMatrix( 90 * deg2rad )); // Rotate
    element.GetGState().SetTransform(mtx);
    writer.WritePlacedElement(element);

The following sample sample illustrates how to use Matrix2D in order to calculate absolute positioning for the text on the page.

    ...
    Matrix2D text_mtx = text_element.GetTextMatrix();
    double x, y;
    for (CharIterator itr = text_element.getCharIterator(); itr.HasNext(); itr.Next()) {
    x = itr.current().x; // character positioning information
    y = itr.current().y;

Get current transformation matrix (CTM)

    Matrix2D ctm = text_element.getCTM();

To get the absolute character positioning information concatenate current text matrix with CTM and then multiply relative postitioning coordinates with the resulting matrix.

    Matrix2D mtx = ctm.multiply(text_mtx);
    mtx.multPoint(x, y);

##### Inheritance

object
Matrix2D

##### Implements

IDisposable

##### Inherited Members

object.ToString()
object.Equals(object)
object.Equals(object, object)
object.ReferenceEquals(object, object)
object.GetHashCode()
object.GetType()
object.MemberwiseClone()

###### Namespace: pdftron.Common

###### Assembly: PDFNet.dll

##### Syntax

    public class Matrix2D : IDisposable

### Constructors

#### Matrix2D()

Creates an identity matrix

##### Declaration

    public Matrix2D()

#### Matrix2D(double, double, double, double, double, double)

Creates a Matrix object based on six numbers that define an affine transformation.

##### Declaration

    public Matrix2D(double a, double b, double c, double d, double h, double v)

##### Parameters

Type | Name | Description
--- | --- | ---
double | a | the matrix element in the first row, first column.
double | b | the matrix element in the first row, second column.
double | c | the matrix element in the second row, first column.
double | d | the matrix element in the second row, second column.
double | h | the matrix element in the third row, first column.
double | v | the matrix element in the third row, second column.

#### Matrix2D(Matrix2D)

Create a matrix and initialize it with values from another matrix

##### Declaration

    public Matrix2D(Matrix2D m)

##### Parameters

Type | Name | Description
--- | --- | ---
Matrix2D | m | matrix to initialize

### Properties

#### m_a

the matrix element in the first row, first column.

##### Declaration

    public double m_a { get; set; }

##### Property Value

Type | Description
--- | ---
double |

#### m_b

the matrix element in the first row, second column

##### Declaration

    public double m_b { get; set; }

##### Property Value

Type | Description
--- | ---
double |

#### m_c

the matrix element in the second row, first column

##### Declaration

    public double m_c { get; set; }

##### Property Value

Type | Description
--- | ---
double |

#### m_d

the matrix element in the second row, second column.

##### Declaration

    public double m_d { get; set; }

##### Property Value

Type | Description
--- | ---
double |

#### m_h

the matrix element in the third row, first column.

##### Declaration

    public double m_h { get; set; }

##### Property Value

Type | Description
--- | ---
double |

#### m_v

the matrix element in the third row, second column.

##### Declaration

    public double m_v { get; set; }

##### Property Value

Type | Description
--- | ---
double |

### Methods

#### Concat(double, double, double, double, double, double)

The Concat method updates this matrix with the product of itself and another matrix specified through an argument list.

##### Declaration

    public void Concat(double a, double b, double c, double d, double h, double v)

##### Parameters

Type | Name | Description
--- | --- | ---
double | a | the matrix element in the first row, first column.
double | b | the matrix element in the first row, second column.
double | c | the matrix element in the second row, first column.
double | d | the matrix element in the second row, second column.
double | h | the matrix element in the third row, first column.
double | v | the matrix element in the third row, second column.

#### Dispose()

Releases all resources used by the Matrix2D

##### Declaration

    public override sealed void Dispose()

#### Dispose(bool)

##### Declaration

    [HandleProcessCorruptedStateExceptions]
    protected virtual void Dispose(bool A_0)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | A_0 |

#### ~Matrix2D()

Allows Matrix2D to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.

##### Declaration

    protected ~Matrix2D()

#### IdentityMatrix()

Create identity matrix {1 0 0 1 0 0}.

##### Declaration

    public static Matrix2D IdentityMatrix()

##### Returns

Type | Description
--- | ---
Matrix2D | the identity matrix

#### Inverse()

If this matrix is invertible, the Inverse method returns its inverse matrix.

##### Declaration

    public Matrix2D Inverse()

##### Returns

Type | Description
--- | ---
Matrix2D | inverse of the matrix

#### Mult(ref double, ref double)

Transform/multiply the point (in_out_x, in_out_y) using this matrix

##### Declaration

    public void Mult(ref double in_out_x, ref double in_out_y)

##### Parameters

Type | Name | Description
--- | --- | ---
double | in_out_x | x coordinate of the result point
double | in_out_y | y coordinate of the result point

#### PostTranslate(double, double)

Updates this matrix by concatenating a translation matrix. M' = M * T(h, v). It is equivalent to this.concat(1,0,0,1,h,v).

##### Declaration

    public Matrix2D PostTranslate(double x, double y)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the horizontal component of the translation.
double | y | the vertical component of the translation.

##### Returns

Type | Description
--- | ---
Matrix2D | this matrix after the update

#### PreTranslate(double, double)

Updates this matrix to the concatenation of a translation matrix and the original matrix. M' = T(h, v) * M. It is equivalent to this.m_h += h; this.m_v += v.

##### Declaration

    public Matrix2D PreTranslate(double x, double y)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the horizontal component of the translation.
double | y | the vertical component of the translation.

##### Returns

Type | Description
--- | ---
Matrix2D | this matrix after the update

#### RotationMatrix(double)

##### Declaration

    public static Matrix2D RotationMatrix(double angle)

##### Parameters

Type | Name | Description
--- | --- | ---
double | angle |

##### Returns

Type | Description
--- | ---
Matrix2D |

#### Scale(double, double)

The Scale method updates this matrix with the product of itself and a scaling matrix.

##### Declaration

    public Matrix2D Scale(double x, double y)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the horizontal scale factor.
double | y | the vertical scale factor

##### Returns

Type | Description
--- | ---
Matrix2D | translated matrix

#### Set(double, double, double, double, double, double)

The Set method sets the elements of this matrix.

##### Declaration

    public void Set(double a, double b, double c, double d, double h, double v)

##### Parameters

Type | Name | Description
--- | --- | ---
double | a | the matrix element in the first row, first column.
double | b | the matrix element in the first row, second column.
double | c | the matrix element in the second row, first column.
double | d | the matrix element in the second row, second column.
double | h | the matrix element in the third row, first column.
double | v | the matrix element in the third row, second column.

#### Set(Matrix2D)

set value to given matrix

##### Declaration

    public void Set(Matrix2D p)

##### Parameters

Type | Name | Description
--- | --- | ---
Matrix2D | p | matrix value for the created matrix

#### Translate(double, double)

The Translate method updates this matrix with the product of itself and a translation matrix (i.e. it is equivalent to this.m_h += h; this.m_v += v).

##### Declaration

    public Matrix2D Translate(double x, double y)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the horizontal component of the translation.
double | y | the vertical component of the translation.

##### Returns

Type | Description
--- | ---
Matrix2D | translated matrix

##### Remarks

This method is deprecated. Please use PreTranslate or PostTranslate instead. The behavior of this method is identical to PreTranslate, but PostTranslate will be more suitable for some use cases.

#### ZeroMatrix()

Create zero matrix (0 0 0 0 0 0).

##### Declaration

    public static Matrix2D ZeroMatrix()

##### Returns

Type | Description
--- | ---
Matrix2D | zero matrix

#### op_Assign(Matrix2D)

assign value from another matrix

##### Declaration

    public Matrix2D op_Assign(Matrix2D rm)

##### Parameters

Type | Name | Description
--- | --- | ---
Matrix2D | rm | another matrix

##### Returns

Type | Description
--- | ---
Matrix2D | matrix with value from `rm`

### Operators

#### operator ==(Matrix2D, Matrix2D)

check if two matrices are equal

##### Declaration

    public static bool operator ==(Matrix2D lm, Matrix2D rm)

##### Parameters

Type | Name | Description
--- | --- | ---
Matrix2D | lm | left matrix
Matrix2D | rm | right matrix

##### Returns

Type | Description
--- | ---
bool | true, if both matrices are equal. false, otherwise.

#### operator !=(Matrix2D, Matrix2D)

check if two matrices are inequal

##### Declaration

    public static bool operator !=(Matrix2D lm, Matrix2D rm)

##### Parameters

Type | Name | Description
--- | --- | ---
Matrix2D | lm | left matrix
Matrix2D | rm | right matrix

##### Returns

Type | Description
--- | ---
bool | true, if both matrices are not equal, false, otherwise.

#### operator *(Matrix2D, Matrix2D)

multiply two matrices

##### Declaration

    public static Matrix2D operator *(Matrix2D lm, Matrix2D rm)

##### Parameters

Type | Name | Description
--- | --- | ---
Matrix2D | lm | left matrix
Matrix2D | rm | right matrix

##### Returns

Type | Description
--- | ---
Matrix2D | multiplication result matrix

### Implements

IDisposable