What Is Transformation Matrix and How to Use It

When you work with objects in a PDF file using the PDFium library, you can use the SetMatrix functions to transform the object (usually an image, but also any other embedded object) in variety of ways. Using the transformation matrix you can rotate, translate (move), scale or shear the image. An example of using the matrix to scale an image to the size of the page in a PDF document can be found here.



Introduction to matrices

If you are very new to linear algebra, matrices are simply set of values grouped together into a rectangular or square form. Here are examples of matrices:



Many physical values can be (and often are) represented in the matrix form. For instance, coordinates; they are often represented as a vector – a matrix with one column and the number of rows for each spatial dimension (2 rows for 2D, 3 rows for 3D and so on). Each element in such a matrix is a coordinate on the corresponding axis. The example of a vector is shown above.

PDF documents also use a coordinate system. The two axes are vertical and horizontal dimensions of a page with each coordinate representing the number of PDF Points on that axis. So, if a given object on the page is placed at 3500 Points from the Bottom and 100 Points from the Left, its coordinate vector is:



which is essentially the same.

Matrices can be summed, subtracted, multiplied and divided (inverted) much like ordinary numbers. Addition and subtraction are the easiest operations, here are examples:

Addition

To add one matrix to another you should simply add each element of the first matrix to the corresponding element of the second matrix. Matrices must be of equal dimensions, of course.



Subtraction

Same thing goes for subtraction except for the arithmetic sign:



Addition and subtraction are commutative. You can change the order of matrices and still get the same result (except for the arithmetic sign in case of subtraction):

A + B = B + A
A - B = -(B - A)

where A and B are matrices.

Multiplication

Multiplying matrices is a more tricky procedure. To multiply a matrix A to a matrix B you should multiple each row of the first matrix to each column of the second matrix. Each such product is the element of the resulting matrix at (i, j) position. Where i is the index of the row in A, and j is the index of a column in B.

Sounds complex? Here is an example:



At first, we multiply the first row of the first matrix to the first column of the second matrix. This gives us the element at (1,1) of the resulting matrix:



Then, we multiply the second row and the first column to calculate the element at (1,2):



Then, we calculate the element at (2,1):



And finally the element at (2,2):



The way matrices are multiplied has two important effects:

1. The number of columns of A must match the number of rows of B. You can multiple 2-by-2 and 2-by-2 matrices as shown above. You can also multiple say 2-by-6 to 4-by-2 (results in a 6-by-4 matrix) or 3-by-3 to 1-by-3 (results in a 3-by-3 matrix). But you cannot multiply 3-by-3 to 1-by-2, for example.
   
2. Multiplication of matrices is NOT commutative. That is . If you take the above example and change the order of matrices the result will be different, namely:

Division

If you thought multiplying of matrices was hard to understand, we have bad news for you: dividing of them is even trickier. However, there is also good news: you don’t need to divide matrices to perform transformation of PDF objects, so we simply leave this Wikipedia link JFYI: https://en.wikipedia.org/wiki/Invertible_matrix

What is a transformation matrix

PDF represents its contents in a two-dimensional coordinate system. Coordinates of every point can be represented as a vector: (x, y). A transformation matrix allows to alter the default coordinate system and map the original coordinates (x, y) to this new coordinate system: (x', y'). Depending on how we alter the coordinate system we effectively rotate, scale, move (translate) or shear the object this way.

A transformation matrix is a 3-by-3 matrix:



Elements of the matrix correspond to various transformations (see below). To transform the coordinate system you should multiply the original coordinate vector to the transformation matrix. Since the matrix is 3-by-3 and the vector is 1-by-2, we need to add an element to it to make the size of the vector match the matrix as required by multiplication rules (see above).

That being said, the transformed vector is obtained as follows:



For example, to rotate an image on the bitmap of a page, the PDF renderer should take coordinates of each point of the image, alter them using the above formula and render that pixel at the new coordinates.

That is what you do when you call the SetMatrix function: you tell the renderer how it should transform each rendered pixel of the object.

Transformation operations

Translate

The translation operation moves the coordinate system by the given offset. The operation results in a new coordinate system that is moved by e along the x axis and by f along the y axis from the original coordinate system.

The transformation matrix for the translation operation is:



Example:

Coordinates of a point in the original coordinate system are (240 651 1). We want to translate the coordinate system by 10 points left and 20 points up. The required transformation matrix is:



The resulting coordinates then are:



As you see, the coordinates changed just like planned. The same way all other pixels of the image are transformed.

The parameters to pass to the SetMatrix method are:



Scale

To scale an object we need to change one of its dimensions or both of them.

The transformation matrix of the scale operation is:



where a and d are respectively horizontal and vertical scaling factors. If they are greater than 1, the object is scaled up. If they are less than 1, the object is scaled down from its original size.

Example:



This matrix will scale the object up by 40% along the x axis and down by 20% along the y axis.



Flip/Reflect

This operation is similar to scaling. We simply need to invert one of the coordinates for horizontal/vertical flip or both of them to reflect about origin.



Horizontal flip:

Vertical flip:

Central flip:



Rotate

The rotation operation rotates the original coordinate system clockwise or counterclockwise for the given angle.

The matrix for the rotation operation is:



where is the rotation angle.

The form of the matrix comes from simple trigonometry, but the formal proof goes beyond the scope of this article.

Let’s say we want to rotate an object by 30 degrees clockwise. Then, each pixel of the object is transformed as follows:





Shear

The transformation matrix for shear in x direction is:



Let’s say we want to shear the object by 20 PDF points right:



And for shear in y direction:



To shear the object by 45 PDF points down:



Multiple transformations

What if you need to apply several transformations to the same object? Like, scale up and rotate? Or flip horizontally for a mirrored image and translate it to the desired position on the page?

In this case you simply need several transformation matrices. To perform a series of transformations, matrices of individual transformations are multiplied together. However, as mentioned above, the multiplication operation is not commutative, hence the order of transformation matrices makes a substantial difference.

For example, if you want to rotate the object, and then translate it, the resulting transformation matrix is:



For the reversed order of transformation matrices the resulting matrix is different though:



It may seem unobvious for the first time. You can move an object by 10 points and then rotate it 45 degrees. Or you can rotate it 45 degrees and move the rotated object by 10 points then. Why the difference? Because the transformation matrix does not rotate (translate, scale etc.) the object, it rotates the coordinate system containing the object.

Think of it this way. Put a pencil on the table. When you transform the object, the sequence of transformations would be “rotate the pencil 45 degrees, then move it left by 10 cm”. But when you transform the coordinate system, you get “rotate the table 45 degrees, then move the table left by 10 cm”.



Conclusion

Now you know what these a, b, c, d, e and f coefficients in the Matrix class mean. The transformation matrix composed of these elements allows to adjust any PDF bitmap or other object almost arbitrary.

Edited by user Sunday, October 13, 2019 4:26:20 AM(UTC)  | Reason: Not specified