Rect
Rect represents a rectangle defined by four floating point numbers x0, y0, x1, y1. They are treated as being coordinates of two diagonally opposite points. The first two numbers are regarded as the “top left” corner P_{(x0,y0)} and P_{(x1,y1)} as the “bottom right” one. However, these two properties need not coincide with their intuitive meanings – read on.
The following remarks are also valid for IRect objects:
A rectangle in the sense of (Py) MuPDF (and PDF) always has borders parallel to the x resp. yaxis. A general orthogonal tetragon is not a rectangle – in contrast to the mathematical definition.
The constructing points can be (almost! – see below) anywhere in the plane – they need not even be different, and e.g. “top left” need not be the geometrical “northwestern” point.
 For any given quadruple of numbers, the geometrically “same” rectangle can be defined in four different ways:
Rect(P_{(x0,y0)}, P_{(x1,y1)})
Rect(P_{(x1,y1)}, P_{(x0,y0)})
Rect(P_{(x0,y1)}, P_{(x1,y0)})
Rect(P_{(x1,y0)}, P_{(x0,y1)})
(Changed in v1.19.0) Hence some classification:
A rectangle is called valid if
x0 <= x1
andy0 <= y1
(i.e. the bottom right point is “southeastern” to the top left one), otherwise invalid. Of the four alternatives above, only the first is valid. Please take into account, that in MuPDF’s coordinate system, the yaxis is oriented from top to bottom. Invalid rectangles have been called infinite in earlier versions.A rectangle is called empty if
x0 >= x1
ory0 >= y1
. This implies, that invalid rectangles are also always empty. Andwidth
(resp.height
) is set to zero ifx0 > x1
(resp.y0 > y1
). In previous versions, a rectangle was empty only if one of width or height was zero.Rectangle coordinates cannot be outside the number range from
FZ_MIN_INF_RECT = 2147483648
toFZ_MAX_INF_RECT = 2147483520
. Both values have been chosen, because they are the smallest / largest 32bit integers that survive C float conversion roundtrips. In previous versions there was no limit for coordinate values.There is exactly one “infinite” rectangle, defined by
x0 = y0 = FZ_MIN_INF_RECT
andx1 = y1 = FZ_MAX_INF_RECT
. It contains every other rectangle. It is mainly used for technical purposes – e.g. when a function call should ignore a formally required rectangle argument. This rectangle is not empty.Rectangles are (semi) open: The right and the bottom edges (including the resp. corners) are not considered part of the rectangle. This implies, that only the topleft corner
(x0, y0)
can ever belong to the rectangle  the other three corners never do. An empty rectangle contains no corners at all.Here is an overview of the changes.
Notion
Versions < 1.19.0
Versions 1.19.*
empty
x0 = x1 or y0 = y1
x0 >= x1 or y0 >= y1 – includes invalid rects
valid
n/a
x0 <= x1 and y0 <= y1
infinite
all rects where x0 > x1 or y1 > y0
exactly one infinite rect / irect!
coordinate values
all numbers
FZ_MIN_INF_RECT <= number <= FZ_MAX_INF_RECT
borders, corners
are parts of the rectangle
right and bottom corners and edges are outside
There are new top level functions defining infinite and standard empty rectangles and quads, see
INFINITE_RECT()
and friends.
Methods / Attributes 
Short Description 

checks containment of point_likes and rect_likes 

calculate rectangle area 

enlarge rectangle to also contain a point 

enlarge rectangle to also contain another one 

common part with another rectangle 

checks for nonempty intersections 

transform with a point and a matrix 

the matrix that transforms to another rectangle 

the Euclidean norm 

makes a rectangle valid 

create smallest IRect containing rectangle 

transform rectangle with a matrix 

bottom left point, synonym bl 

bottom right point, synonym br 

rectangle height 

equals result of method round() 

whether rectangle is empty 

whether rectangle is valid 

whether rectangle is infinite 

top left point, synonym tl 

top_right point, synonym tr 

Quad made from rectangle corners 

rectangle width 

left corners’ x coordinate 

right corners’ x coordinate 

top corners’ y coordinate 

bottom corners’ y coordinate 
Class API
 class Rect
 __init__(self)
 __init__(self, x0, y0, x1, y1)
 __init__(self, top_left, bottom_right)
 __init__(self, top_left, x1, y1)
 __init__(self, x0, y0, bottom_right)
 __init__(self, rect)
 __init__(self, sequence)
Overloaded constructors: top_left, bottom_right stand for
point_like
objects, “sequence” is a Python sequence type of 4 numbers (see Using Python Sequences as Arguments in PyMuPDF), “rect” means anotherrect_like
, while the other parameters mean coordinates.If “rect” is specified, the constructor creates a new copy of it.
Without parameters, the empty rectangle Rect(0.0, 0.0, 0.0, 0.0) is created.
 round()
Creates the smallest containing IRect. This is not the same as simply rounding the rectangle’s edges: The top left corner is rounded upwards and to the left while the bottom right corner is rounded downwards and to the right.
>>> fitz.Rect(0.5, 0.01, 123.88, 455.123456).round() IRect(0, 1, 124, 456)
If the rectangle is empty, the result is also empty.
Possible paradox: The result may be empty, even if the rectangle is not empty! In such cases, the result obviously does not contain the rectangle. This is because MuPDF’s algorithm allows for a small tolerance (1e3). Example:
>>> r = fitz.Rect(100, 100, 200, 100.001) >>> r.is_empty # rect is NOT empty False >>> r.round() # but its irect IS empty! fitz.IRect(100, 100, 200, 100) >>> r.round().is_empty True
 Return type
 transform(m)
Transforms the rectangle with a matrix and replaces the original. If the rectangle is empty or infinite, this is a nooperation.
 Parameters
m (Matrix) – The matrix for the transformation.
 Return type
Rect
 Returns
the smallest rectangle that contains the transformed original.
 intersect(r)
The intersection (common rectangular area, largest rectangle contained in both) of the current rectangle and r is calculated and replaces the current rectangle. If either rectangle is empty, the result is also empty. If r is infinite, this is a nooperation. If the rectangles are (mathematically) disjoint sets, then the result is invalid. If the result is valid but empty, then the rectangles touch each other in a corner or (part of) a side.
 Parameters
r (Rect) – Second rectangle
 include_rect(r)
The smallest rectangle containing the current one and r is calculated and replaces the current one. If either rectangle is infinite, the result is also infinite. If one is empty, the other one will be taken as the result.
 Parameters
r (Rect) – Second rectangle
 include_point(p)
The smallest rectangle containing the current one and point p is calculated and replaces the current one. The infinite rectangle remains unchanged. To create a rectangle containing a series of points, start with (the empty) fitz.Rect(p1, p1) and successively include the remaining points.
 Parameters
p (Point) – Point to include.
 get_area([unit])
Calculate the area of the rectangle and, with no parameter, equals abs(rect). Like an empty rectangle, the area of an infinite rectangle is also zero. So, at least one of fitz.Rect(p1, p2) and fitz.Rect(p2, p1) has a zero area.
 Parameters
unit (str) – Specify required unit: respective squares of px (pixels, default), in (inches), cm (centimeters), or mm (millimeters).
 Return type
float
 contains(x)
Checks whether x is contained in the rectangle. It may be an IRect, Rect, Point or number. If x is an empty rectangle, this is always true. If the rectangle is empty this is always False for all nonempty rectangles and for all points.
x in rect
andrect.contains(x)
are equivalent. Parameters
x (
rect_like
orpoint_like
.) – the object to check. Return type
bool
 intersects(r)
Checks whether the rectangle and a
rect_like
“r” contain a common nonempty Rect. This will always be False if either is infinite or empty. Parameters
r (rect_like) – the rectangle to check.
 Return type
bool
 torect(rect)
New in version 1.19.3
Compute the matrix which transforms this rectangle to a given one.
 Parameters
rect (rect_like) – the target rectangle. Must not be empty or infinite.
 Return type
 Returns
a matrix
mat
such thatself * mat = rect
. Can for example be used to transform between the page and the pixmap coordinates.Note
Suppose you want to check whether any of the words “pixmap” is invisible, because the text color equals the ambient color – e.g. white on white. We make a pixmap and check the “color environment” of each word:
>>> # make a pixmap of the page >>> pix = page.get_pixmap(dpi=150) >>> # make a matrix that transforms to pixmap coordinates >>> mat = page.rect.torect(pix.irect) >>> # search for text locations >>> rlist = page.search_for("pixmap") >>> # check color environment of each occurrence >>> # we will check for "almost unicolor" >>> for r in rlist: if pix.color_topusage(clip=r * mat)[0] > 0.95: print("'pixmap' invisible here:", r) >>>
Method
Pixmap.color_topusage()
computes the percentage of pixels showing the same color.
 morph(fixpoint, matrix)
New in version 1.17.0
Return a new quad after applying a matrix to the rectangle using the fixed point
fixpoint
. Parameters
fixpoint (point_like) – the fixed point.
matrix (matrix_like) – the matrix.
 Returns
a new Quad. This a wrapper for the samenamed quad method. If infinite, the infinite quad is returned.
 norm()
New in version 1.16.0
Return the Euclidean norm of the rectangle treated as a vector of four numbers.
 normalize()
Replace the rectangle with its valid version. This is done by shuffling the rectangle corners. After completion of this method, the bottom right corner will indeed be southeastern to the top left one (but may still be empty).
 irect
Equals result of method round().
 top_left
 top_right
 bottom_left
 bottom_right
 width
Width of the rectangle. Equals
max(x1  x0, 0)
. Return type
float
 height
Height of the rectangle. Equals
max(y1  y0, 0)
. Return type
float
 x0
Xcoordinate of the left corners.
 Type
float
 y0
Ycoordinate of the top corners.
 Type
float
 x1
Xcoordinate of the right corners.
 Type
float
 y1
Ycoordinate of the bottom corners.
 Type
float
 is_infinite
True
if this is the infinite rectangle. Type
bool
 is_empty
True
if rectangle is empty. Type
bool
 is_valid
True
if rectangle is valid. 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.
Rectangles can be used with arithmetic operators – see chapter Operator Algebra for Geometry Objects.
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.