Summary: Ctors | Methods | Inherited Methods | [Expand All]
public class

# Matrix2D

extends Object
implements AutoCloseable

java.lang.Object
↳ | com.pdftron.common.Matrix2D

## Class Overview

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);

>      }

## Summary

Public Constructors
| Matrix2D() Creates an identity matrix
| Matrix2D(double a, double b, double c, double d, double h, double v) Creates a Matrix object based on six numbers that define an affine transformation.

Public Methods
static Matrix2D | __Create(long impl)
long | __GetHandle()
void | close() Frees the native memory of the object.
void | concat(double a, double b, double c, double d, double h, double v) The Concat method updates this matrix with the product of itself and another matrix specified through an argument list.
void | destroy() Frees the native memory of the object.
boolean | equals(Object m) equals determines whether the elements of this matrix are equal to the elements of another matrix.
double | getA() Get a, the matrix element in the first row, second column.
double | getB() Get b, the matrix element in the first row, second column Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.
double | getC() Get c, the matrix element in the second row, first column Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.
double | getD() Get d, the matrix element in the second row, second column.
double | getH() Get h, the matrix element in the third row, first column.
double | getV() Get v, the matrix element in the third row, second column.
int | hashCode()
static Matrix2D | identityMatrix() Create identity matrix (1 0 0 1 0 0).
Matrix2D | inverse() If this matrix is invertible, the Inverse method returns its inverse matrix.
Point2D.Double | multPoint(double in_x, double in_y) Transform/multiply the point (in_out_x, in_out_y) using this matrix.
Matrix2D | multiply(Matrix2D m) Multiplies this matrix with another matrix and return the result in a new matrix.
Matrix2D | postTranslate(double h, double v) Updates this matrix by concatenating a translation matrix.
Matrix2D | preTranslate(double h, double v) Updates this matrix to the concatenation of a translation matrix and the original matrix.
static Matrix2D | rotationMatrix(double angle) Rotation matrix.
Matrix2D | scale(double h, double v) The Scale method updates this matrix with the product of itself and a scaling matrix.
void | set(double a, double b, double c, double d, double h, double v) The Set method sets the elements of this matrix.
void | setA(double a) Set a, the matrix element in the first row, first column.
void | setB(double b) Set b, the matrix element in the first row, second column Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.
void | setC(double c) Set c, the matrix element in the second row, first column.
void | setD(double d) Set d, the matrix element in the second row, second column.
void | setH(double h) Set h, the matrix element in the third row, first column.
void | setV(double v) Set v, the matrix element in the third row, second column.
Matrix2D | translate(double h, double v) The Translate method updates this matrix with the product of itself and a translation matrix (i.e.
static Matrix2D | zeroMatrix() Create zero matrix (0 0 0 0 0 0).

[Expand] Inherited Methods
From class java.lang.Object
boolean | equals(Object arg0)
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()
From interface java.lang.AutoCloseable
abstract void | close()

## Public Constructors

#### public Matrix2D ()

Creates an identity matrix

##### Throws

PDFNetException |

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

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

##### Parameters

a | the a
b | the b
c | the c
d | the d
h | the h
v | the v

##### Throws

PDFNetException |

## Public Methods

#### public static Matrix2D __Create (long impl)

#### public long __GetHandle ()

#### public void close ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

##### Throws

PDFNetException |

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

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

##### Parameters

a | the matrix element in the first row, first column.
b | the matrix element in the first row, second column.
c | the matrix element in the second row, first column.
d | the matrix element in the second row, second column.
h | the matrix element in the third row, first column.
v | the matrix element in the third row, second column.

##### Throws

PDFNetException |

#### public void destroy ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

##### Throws

PDFNetException |

#### public boolean equals (Object m)

equals determines whether the elements of this matrix are equal to the elements of another matrix.

##### Parameters

m | A Matrix object that is compared with this Matrix object.

##### Returns

- true, if successful

#### public double getA ()

Get a, the matrix element in the first row, second column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Returns

- a, the matrix element in the first row, first column

##### Throws

PDFNetException |

#### public double getB ()

Get b, the matrix element in the first row, second column

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Returns

- b, the matrix element in the first row, second column

##### Throws

PDFNetException |

#### public double getC ()

Get c, the matrix element in the second row, first column

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Returns

- c, the matrix element in the second row, first column

##### Throws

PDFNetException |

#### public double getD ()

Get d, the matrix element in the second row, second column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Returns

- d, the matrix element in the second row, second column.

##### Throws

PDFNetException |

#### public double getH ()

Get h, the matrix element in the third row, first column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Returns

- h, the matrix element in the third row, first column.

##### Throws

PDFNetException |

#### public double getV ()

Get v, the matrix element in the third row, second column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Returns

- v, the matrix element in the third row, second column.

##### Throws

PDFNetException |

#### public int hashCode ()

#### public static Matrix2D identityMatrix ()

Create identity matrix (1 0 0 1 0 0).

##### Returns

- the identity matrix

##### Throws

PDFNetException |

#### public Matrix2D inverse ()

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

##### Returns

- inverse of the matrix

##### Throws

PDFNetException |

#### public Point2D.Double multPoint (double in_x, double in_y)

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

##### Parameters

in_x | x coordinate of the given point
in_y | y coordinate of the given point

##### Returns

- transformation result

##### Throws

PDFNetException |

#### public Matrix2D multiply (Matrix2D m)

Multiplies this matrix with another matrix and return the result in a new matrix.

##### Parameters

m | another Matrix2D object

##### Returns

- a matrix representing the product of this matrix and given matrix 'm'.

##### Throws

PDFNetException |

#### public Matrix2D postTranslate (double h, double v)

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

##### Parameters

h | the horizontal component of the translation.
v | the vertical component of the translation.

##### Returns

- this matrix after the update

##### Throws

PDFNetException |

#### public Matrix2D preTranslate (double h, double v)

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.

##### Parameters

h | the horizontal component of the translation.
v | the vertical component of the translation.

##### Returns

- this matrix after the update

##### Throws

PDFNetException |

#### public static Matrix2D rotationMatrix (double angle)

Rotation matrix.

##### Parameters

angle | the angle of rotation in radians. Positive values specify clockwise rotation.

##### Returns

- A rotation matrix for a given angle.

##### Throws

PDFNetException |

#### public Matrix2D scale (double h, double v)

The Scale method updates this matrix with the product of itself and a scaling matrix. (i.e. it is equivalent to this.m_a *= h; this.m_d *= v).

##### Parameters

h | the horizontal scale factor.
v | the vertical scale factor

##### Returns

- updated this matrix

##### Throws

PDFNetException |

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

The Set method sets the elements of this matrix.

##### Parameters

a | the matrix element in the first row, first column.
b | the matrix element in the first row, second column.
c | the matrix element in the second row, first column.
d | the matrix element in the second row, second column.
h | the matrix element in the third row, first column.
v | the matrix element in the third row, second column.

##### Throws

PDFNetException |

#### public void setA (double a)

Set a, the matrix element in the first row, first column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Parameters

a | the new a (the matrix element in the first row, first column)

##### Throws

PDFNetException |

#### public void setB (double b)

Set b, the matrix element in the first row, second column

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Parameters

b | the new b, the matrix element in the first row, second column

##### Throws

PDFNetException |

#### public void setC (double c)

Set c, the matrix element in the second row, first column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Parameters

c | the new c, the matrix element in the second row, first column.

##### Throws

PDFNetException |

#### public void setD (double d)

Set d, the matrix element in the second row, second column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Parameters

d | the new d, the matrix element in the second row, second column.

##### Throws

PDFNetException |

#### public void setH (double h)

Set h, the matrix element in the third row, first column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Parameters

h | the new h, the matrix element in the third row, first column.

##### Throws

PDFNetException |

#### public void setV (double v)

Set v, the matrix element in the third row, second column.

Matrix2D elements are positioned as follows : { a b 0 c d 0 h v 1 }.

##### Parameters

v | the new v, the matrix element in the third row, second column.

##### Throws

PDFNetException |

#### public Matrix2D translate (double h, double v)

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

##### Parameters

h | the horizontal component of the translation.
v | the vertical component of the translation.

##### Returns

- this matrix after the update Note:

  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.

##### Throws

PDFNetException |

#### public static Matrix2D zeroMatrix ()

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

##### Returns

- zero matrix

##### Throws

PDFNetException |