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:

<ul><li>   
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.
</li><li>
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.
</li><li>
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.
</li><li>
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')


<example>
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.
<pre><code class="lang-csharp">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);</code></pre>

The following sample sample illustrates how to use Matrix2D in order to calculate 
absolute positioning for the text on the page.
<pre><code class="lang-csharp">...
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;</code></pre>


Get current transformation matrix (CTM)
<pre><code class="lang-csharp">Matrix2D ctm = text_element.getCTM();</code></pre>

To get the absolute character positioning information concatenate current 
text matrix with CTM and then multiply relative postitioning coordinates with 
the resulting matrix.
<pre><code class="lang-csharp">Matrix2D mtx = ctm.multiply(text_mtx);
mtx.multPoint(x, y);</code></pre>	
</example>
Inheritance
object
Matrix2D
Implements
Inherited Members
Namespace: pdftron.Common
Assembly: PDFTronDotNet.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()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public void Dispose()

Dispose(bool)

Declaration
protected virtual void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

~Matrix2D()

Releases all resources used by the Matrix2D

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

RotationMatrix(double)

Rotation matrix.

Declaration
public static Matrix2D RotationMatrix(double angle)
Parameters
Type Name Description
double angle

the angle of rotation in radians. Positive values specify clockwise rotation.
Returns
Type Description
Matrix2D

A rotation matrix for a given angle.

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

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