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 Px0,y0 and Px1,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:
Rectangle borders are always parallel to the respective X- and Y-axes.
The constructing points can be anywhere in the plane – they need not even be different, and e.g. “top left” need not be the geometrical “north-western” point.
For any given quadruple of numbers, the geometrically “same” rectangle can be defined in (up to) four different ways: Rect(Px0,y0, Px1,y1), Rect(Px1,y1, Px0,y0), Rect(Px0,y1, Px1,y0), and Rect(Px1,y0, Px0,y1).
Hence some useful classification:
A rectangle is called finite if x0 <= x1 and y0 <= y1 (i.e. the bottom right point is “south-eastern” to the top left one), otherwise infinite. Of the four alternatives above, only one is finite (disregarding degenerate cases). Please take into account, that in MuPDF’s coordinate system the y-axis is oriented from top to bottom.
A rectangle is called empty if x0 = x1 or y0 = y1, i.e. if its area is zero.
Note
It sounds like a paradox: a rectangle can be both, infinite and empty …
Methods / Attributes |
Short Description |
---|---|
checks containment of another object |
|
calculate rectangle area |
|
calculate rectangle area |
|
enlarge rectangle to also contain a point |
|
enlarge rectangle to also contain another one |
|
common part with another rectangle |
|
checks for non-empty intersections |
|
transform with a point and a matrix |
|
the Euclidean norm |
|
makes a rectangle finite |
|
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 infinite |
|
top left point, synonym tl |
|
top_right point, synonym tr |
|
Quad made from rectangle corners |
|
rectangle width |
|
top left corner’s X-coordinate |
|
bottom right corner’s X-coordinate |
|
top left corner’s Y-coordinate |
|
bottom right corner’s 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 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 infinite, the “normalized” (finite) version of it will be taken. The result of this method is always a finite IRect.
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 (1e-3). Example:
>>> r = fitz.Rect(100, 100, 200, 100.001) >>> r.isEmpty # rect is NOT empty False >>> r.round() # but its irect IS empty! fitz.IRect(100, 100, 200, 100) >>> r.round().isEmpty 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 no-operation.
- 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) 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 no-operation.
- Parameters
r (Rect) – Second rectangle
-
includeRect
(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
-
includePoint
(p)¶ The smallest rectangle containing the current one and point p is calculated and replaces the current one. Infinite rectangles remain unchanged. To create a rectangle containing a series of points, start with (the empty) fitz.Rect(p1, p1) and successively perform includePoint operations for the other points.
- Parameters
p (Point) – Point to include.
-
getRectArea
([unit])¶
-
getArea
([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 non-empty rectangles and for all points. If x is a number, it will be checked against the four components. x in rect and rect.contains(x) are equivalent.
-
intersects
(r)¶ Checks whether the rectangle and a
rect_like
“r” contain a common non-empty Rect. This will always be False if either is infinite or empty.- Parameters
r (rect_like) – the rectangle to check.
- Return type
bool
-
morph
(fixpoint, matrix)¶ (New in version 1.17.0)
Return a new quad after applying a matrix to it using a fixed point.
- Parameters
fixpoint (point_like) – the fixed point.
matrix (matrix_like) – the matrix.
- Returns
a new Quad. This a wrapper for the same-named quad method.
-
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 finite version. This is done by shuffling the rectangle corners. After completion of this method, the bottom right corner will indeed be south-eastern to the top left one.
-
irect
¶ Equals result of method round().
-
top_left
¶
-
top_right
¶
-
bottom_left
¶
-
bottom_right
¶
-
width
¶ Width of the rectangle. Equals abs(x1 - x0).
- Return type
float
-
height
¶ Height of the rectangle. Equals abs(y1 - y0).
- Return type
float
-
x0
¶ X-coordinate of the left corners.
- Type
float
-
y0
¶ Y-coordinate of the top corners.
- Type
float
-
x1
¶ X-coordinate of the right corners.
- Type
float
-
y1
¶ Y-coordinate of the bottom corners.
- Type
float
-
isInfinite
¶ True if rectangle is infinite, False otherwise.
- Type
bool
-
isEmpty
¶ True if rectangle is empty, False otherwise.
- 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.