Matrix
Matrix is a rowmajor 3x3 matrix used by image transformations in MuPDF (which complies with the respective concepts laid down in the Adobe PDF References). With matrices you can manipulate the rendered image of a page in a variety of ways: (parts of) the page can be rotated, zoomed, flipped, sheared and shifted by setting some or all of just six float values.
Since all points or pixels live in a twodimensional space, one column vector of that matrix is a constant unit vector, and only the remaining six elements are used for manipulations. These six elements are usually represented by [a, b, c, d, e, f]. Here is how they are positioned in the matrix:
Please note:
the below methods are just convenience functions – everything they do, can also be achieved by directly manipulating the six numerical values
all manipulations can be combined – you can construct a matrix that rotates and shears and scales and shifts, etc. in one go. If you however choose to do this, do have a look at the remarks further down or at the Adobe PDF References.
Method / Attribute 
Description 

perform a rotation 

perform a scaling 

perform a shearing (skewing) 

perform a translation (shifting) 

perform a matrix multiplication 

calculate the inverted matrix 

the Euclidean norm 

zoom factor X direction 

shearing effect Y direction 

shearing effect X direction 

zoom factor Y direction 

horizontal shift 

vertical shift 

true if rect corners will remain rect corners 
Class API
 class Matrix
 __init__(self)
 __init__(self, zoomx, zoomy)
 __init__(self, shearx, sheary, 1)
 __init__(self, a, b, c, d, e, f)
 __init__(self, matrix)
 __init__(self, degree)
 __init__(self, sequence)
Overloaded constructors.
Without parameters, the zero matrix Matrix(0.0, 0.0, 0.0, 0.0, 0.0, 0.0) will be created.
zoom* and shear* specify zoom or shear values (float) and create a zoom or shear matrix, respectively.
For “matrix” a new copy of another matrix will be made.
Float value “degree” specifies the creation of a rotation matrix which rotates anticlockwise.
A “sequence” must be any Python sequence object with exactly 6 float entries (see Using Python Sequences as Arguments in PyMuPDF).
fitz.Matrix(1, 1), fitz.Matrix(0.0 and *fitz.Matrix(fitz.Identity) create modifiable versions of the Identity matrix, which looks like [1, 0, 0, 1, 0, 0].
 norm()
New in version 1.16.0
Return the Euclidean norm of the matrix as a vector.
 prerotate(deg)
Modify the matrix to perform a counterclockwise rotation for positive deg degrees, else clockwise. The matrix elements of an identity matrix will change in the following way:
[1, 0, 0, 1, 0, 0] > [cos(deg), sin(deg), sin(deg), cos(deg), 0, 0].
 Parameters
deg (float) – The rotation angle in degrees (use conventional notation based on Pi = 180 degrees).
 prescale(sx, sy)
Modify the matrix to scale by the zoom factors sx and sy. Has effects on attributes a thru d only: [a, b, c, d, e, f] > [a*sx, b*sx, c*sy, d*sy, e, f].
 Parameters
sx (float) – Zoom factor in X direction. For the effect see description of attribute a.
sy (float) – Zoom factor in Y direction. For the effect see description of attribute d.
 preshear(sx, sy)
Modify the matrix to perform a shearing, i.e. transformation of rectangles into parallelograms (rhomboids). Has effects on attributes a thru d only: [a, b, c, d, e, f] > [c*sy, d*sy, a*sx, b*sx, e, f].
 Parameters
sx (float) – Shearing effect in X direction. See attribute c.
sy (float) – Shearing effect in Y direction. See attribute b.
 pretranslate(tx, ty)
Modify the matrix to perform a shifting / translation operation along the x and / or y axis. Has effects on attributes e and f only: [a, b, c, d, e, f] > [a, b, c, d, tx*a + ty*c, tx*b + ty*d].
 Parameters
tx (float) – Translation effect in X direction. See attribute e.
ty (float) – Translation effect in Y direction. See attribute f.
 concat(m1, m2)
Calculate the matrix product m1 * m2 and store the result in the current matrix. Any of m1 or m2 may be the current matrix. Be aware that matrix multiplication is not commutative. So the sequence of m1, m2 is important.
 invert(m=None)
Calculate the matrix inverse of m and store the result in the current matrix. Returns 1 if m is not invertible (“degenerate”). In this case the current matrix will not change. Returns 0 if m is invertible, and the current matrix is replaced with the inverted m.
 Parameters
m (Matrix) – Matrix to be inverted. If not provided, the current matrix will be used.
 Return type
int
 a
Scaling in Xdirection (width). For example, a value of 0.5 performs a shrink of the width by a factor of 2. If a < 0, a leftright flip will (additionally) occur.
 Type
float
 b
Causes a shearing effect: each Point(x, y) will become Point(x, y  b*x). Therefore, looking from left to right, e.g. horizontal lines will be “tilt” – downwards if b > 0, upwards otherwise (b is the tangent of the tilting angle).
 Type
float
 c
Causes a shearing effect: each Point(x, y) will become Point(x  c*y, y). Therefore, looking upwards, vertical lines will be “tilt” – to the left if c > 0, to the right otherwise (c is the tangent of the tilting angle).
 Type
float
 d
Scaling in Ydirection (height). For example, a value of 1.5 performs a stretch of the height by 50%. If d < 0, an updown flip will (additionally) occur.
 Type
float
 e
Causes a horizontal shift effect: Each Point(x, y) will become Point(x + e, y). Positive (negative) values of e will shift right (left).
 Type
float
 f
Causes a vertical shift effect: Each Point(x, y) will become Point(x, y  f). Positive (negative) values of f will shift down (up).
 Type
float
 is_rectilinear
Rectilinear means that no shearing is present and that any rotations are integer multiples of 90 degrees. Usually this is used to confirm that (axisaligned) rectangles before the transformation are still axisaligned rectangles afterwards.
 Type
bool
Note
This class adheres to the Python sequence protocol, so components can be accessed via their index, too. Also refer to Using Python Sequences as Arguments in PyMuPDF.
A matrix can be used with arithmetic operators – see chapter Operator Algebra for Geometry Objects.
Changes of matrix properties and execution of matrix methods can be executed consecutively. This is the same as multiplying the respective matrices.
Matrix multiplication is not commutative – changing the execution sequence in general changes the result. So it can quickly become unclear which result a transformation will yield.
Examples
Here are examples to illustrate some of the effects achievable. The following pictures start with a page of the PDF version of this help file. We show what happens when a matrix is being applied (though always full pages are created, only parts are displayed here to save space).
This is the original page image:
Shifting
We transform it with a matrix where e = 100 (right shift by 100 pixels).
Next we do a down shift by 100 pixels: f = 100.
Flipping
Flip the page leftright (a = 1).
Flip updown (d = 1).
Shearing
First a shear in Y direction (b = 0.5).
Second a shear in X direction (c = 0.5).
Rotating
Finally a rotation by 30 clockwise degrees (prerotate(30)).
This software is provided ASIS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.