The Transformation Class

class pypdf.Transformation(ctm: tuple[float, float, float, float, float, float] = (1, 0, 0, 1, 0, 0))

Bases: object

Represent a 2D transformation.

The transformation between two coordinate systems is represented by a 3-by-3 transformation matrix with the following form:

a b 0
c d 0
e f 1

Because a transformation matrix has only six elements that can be changed, it is usually specified in PDF as the six-element array [ a b c d e f ].

Coordinate transformations are expressed as matrix multiplications:

                            a b 0
[ x′ y′ 1 ] = [ x y 1 ] ×   c d 0
                            e f 1

Example

>>> from pypdf import PdfWriter, Transformation
>>> page = PdfWriter().add_blank_page(800, 600)
>>> op = Transformation().scale(sx=2, sy=3).translate(tx=10, ty=20)
>>> page.add_transformation(op)

property matrix: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]

Return the transformation matrix as a tuple of tuples in the form:

((a, b, 0), (c, d, 0), (e, f, 1))

static compress(matrix: tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]) → tuple[float, float, float, float, float, float]

Compresses the transformation matrix into a tuple of (a, b, c, d, e, f).

Parameters:

matrix – The transformation matrix as a tuple of tuples.

Returns:

A tuple representing the transformation matrix as (a, b, c, d, e, f)

transform(m: Transformation) → Transformation

Apply one transformation to another.

Parameters:

m – a Transformation to apply.

Returns:

A new Transformation instance

Example

>>> from pypdf import PdfWriter, Transformation
>>> height, width = 40, 50
>>> page = PdfWriter().add_blank_page(800, 600)
>>> op = Transformation((1, 0, 0, -1, 0, height)) # vertical mirror
>>> op = Transformation().transform(Transformation((-1, 0, 0, 1, width, 0)))  # horizontal mirror
>>> page.add_transformation(op)

translate(tx: float = 0, ty: float = 0) → Transformation

Translate the contents of a page.

Parameters:

• tx – The translation along the x-axis.

• ty – The translation along the y-axis.

Returns:

A new Transformation instance

scale(sx: float | None = None, sy: float | None = None) → Transformation

Scale the contents of a page towards the origin of the coordinate system.

Typically, that is the lower-left corner of the page. That can be changed by translating the contents / the page boxes.

Parameters:

• sx – The scale factor along the x-axis.

• sy – The scale factor along the y-axis.

Returns:

A new Transformation instance with the scaled matrix.

rotate(rotation: float) → Transformation

Rotate the contents of a page.

Parameters:

rotation – The angle of rotation in degrees.

Returns:

A new Transformation instance with the rotated matrix.

apply_on(pt: list[float], as_object: bool = False) → list[float]

apply_on(pt: tuple[float, float], as_object: bool = False) → tuple[float, float]

Apply the transformation matrix on the given point.

Parameters:

• pt – A tuple or list representing the point in the form (x, y).

• as_object – If True, return items as FloatObject, otherwise as plain floats.

Returns:

A tuple or list representing the transformed point in the form (x’, y’)