Quad

Represents a four-sided mathematical shape (also called “quadrilateral” or “tetragon”) in the plane, defined as a sequence of four Point objects ul, ur, ll, lr (conveniently called upper left, upper right, lower left, lower right).

Quads can be obtained as results of text search methods (Page.searchFor()), and they are used to define text marker annotations (see e.g. Page.addSquigglyAnnot() and friends), and in several draw methods (like Page.drawQuad() / Shape.drawQuad(), Page.drawOval()/ :meth`Shape.drawQuad`).

Note

  • If the corners of a rectangle are transformed with a rotation, scale or translation Matrix, then the resulting quad is rectangular, i.e. its corners again enclose angles of 90 degrees. Property Quad.isRectangular checks whether a quad can be thought of being the result of such an operation. This is not true for all matrices: e.g. shear matrices produce parallelograms, and non-invertible matrices deliver “degenerate” tetragons like triangles or lines.

  • Attribute Quad.rect obtains the envelopping rectangle. Vice versa, rectangles now have attributes Rect.quad, resp. IRect.quad to obtain their respective tetragon versions.

Methods / Attributes

Short Description

Quad.transform()

transform with a matrix

Quad.morph()

transform with a point and matrix

Quad.ul

upper left point

Quad.ur

upper right point

Quad.ll

lower left point

Quad.lr

lower right point

Quad.isConvex

true if quad is a convex set

Quad.isEmpty

true if quad is an empty set

Quad.isRectangular

true if quad is a (rotated) rectangle

Quad.rect

smallest containing Rect

Quad.width

the longest width value

Quad.height

the longest height value

Class API

class Quad
__init__(self)
__init__(self, ul, ur, ll, lr)
__init__(self, quad)
__init__(self, sequence)

Overloaded constructors: “ul”, “ur”, “ll”, “lr” stand for point_like objects (the four corners), “sequence” is a Python sequence with four point_like objects.

If “quad” is specified, the constructor creates a new copy of it.

Without parameters, a quad consisting of 4 copies of Point(0, 0) is created.

transform(matrix)

Modify the quadrilateral by transforming each of its corners with a matrix.

Parameters

matrix (matrix_like) – the matrix.

morph(point, matrix)

(New in version 1.17.0) “Morph” the quad with a matrix-like using a point-like as pivotal point.

Parameters
  • point (point_like) – the point.

  • matrix (matrix_like) – the matrix.

Returns

a new quad. The effect is achieved by using the following code snippet:

>>> T = fitz.Matrix(1, 1).preTranslate(point.x, point.y)
>>> result = self * ~T * matrix * T

Typical uses include rotating the quad around a desired point.

rect

The smallest rectangle containing the quad, represented by the blue area in the following picture.

_images/img-quads.jpg
Type

Rect

ul

Upper left point.

Type

Point

ur

Upper right point.

Type

Point

ll

Lower left point.

Type

Point

lr

Lower right point.

Type

Point

isConvex

(New in version 1.16.1)

True if all lines are contained in the quad which connect two points of the quad.

Type

bool

isEmpty

True if enclosed area is zero, which means that all four points are on the same line. If this is false, the quad may still be degenerate or not look like a rectangle at all (triangles, parallelograms, trapezoids, …).

Type

bool

isRectangular

True if all angles are 90 degrees. This also implies that the area is not empty and convex.

Type

bool

width

The maximum length of the top and the bottom side.

Type

float

height

The maximum length of the left and the right side.

Type

float

Remark

This class adheres to the sequence protocol, so components can be dealt with via their indices, too. Also refer to Using Python Sequences as Arguments in PyMuPDF.

We are still in process to extend algebraic operations to quads. Multiplication and division with / by numbers and matrices are already defined. Addition, subtraction and any unary operations may follow when we see an actual need.