Rect
Rect
represents a rectangle defined by four floating point numbers x0, y0, x1, y1. They are viewed 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
andy0 <= 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). - A rectangle is called empty if
x0 = x1
ory0 = 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 |
---|---|
Rect.contains() |
checks containment of another object |
Rect.getArea() |
calculate rectangle area |
Rect.getRectArea() |
calculate rectangle area |
Rect.includePoint() |
enlarge rectangle to also contain a point |
Rect.includeRect() |
enlarge rectangle to also contain another one |
Rect.intersect() |
common part with another rectangle |
Rect.intersects() |
checks for non-empty intersections |
Rect.normalize() |
makes a rectangle finite |
Rect.round() |
create smallest IRect containing rectangle |
Rect.transform() |
transform rectangle with a matrix |
Rect.bottom_left |
bottom left point, synonym bl |
Rect.bottom_right |
bottom right point, synonym br |
Rect.height |
rectangle height |
Rect.irect |
equals result of method round() |
Rect.isEmpty |
whether rectangle is empty |
Rect.isInfinite |
whether rectangle is infinite |
Rect.top_left |
top left point, synonym tl |
Rect.top_right |
top_right point, synonym tr |
Rect.width |
rectangle width |
Rect.x0 |
top left corner’s X-coordinate |
Rect.x1 |
bottom right corner’s X-coordinate |
Rect.y0 |
top left corner’s Y-coordinate |
Rect.y1 |
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, list) Overloaded constructors:
top_left
,bottom_right
stand for Point objects,list
is a Python sequence type with length 4,rect
means anotherRect
, while the other parameters mean float coordinates. Iflist
is specified, it is the user’s responsibility to only provide numeric entries - no error checking is done, and invalid entries will receive a value of-1.0
.If
rect
is specified, the constructor creates a new copy ofrect
.Without parameters, the 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!).
- 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 False >>> r.round() fitz.IRect(100, 100, 200, 100) >>> r.round().isEmpty True
To reproduce the effect on your platform, you may need to adjust the numbers a little.
Return type: IRect - If the rectangle is infinite, the “normalized” (finite) version of it will be taken. The result of this method is always a finite
-
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. Ifr
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 performincludePoint
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 offitz.Rect(p1, p2)
andfitz.Rect(p2, p1)
has a zero area.Parameters: unit (str) – Specify required unit: respective squares of px
(pixels, default),in
(inches),cm
(centimeters), ormm
(millimeters).Return type: float
-
contains
(x) Checks whether
x
is contained in the rectangle. It may be anIRect
,Rect
,Point
or number. Ifx
is an empty rectangle, this is always true. If the rectangle is empty this is alwaysFalse
for all non-empty rectangles and for all points. Ifx
is a number, it will be checked against the four components.x in rect
andrect.contains(x)
are equivalent.Parameters: x (IRect or Rect or Point or number) – the object to check. Return type: bool
-
intersects
(r) Checks whether the rectangle and
r
(aRect
or IRect) have a non-empty rectangle in common. This will always beFalse
if either is infinite or empty.Parameters: r (IRect or Rect) – the rectangle to check. Return type: bool
-
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
-
tl
Equals
Point(x0, y0)
.Type: Point
-
top_right
-
tr
Equals
Point(x1, y0)
.Type: Point
-
bottom_left
-
bl
Equals
Point(x0, y1)
.Type: Point
-
bottom_right
-
br
Equals
Point(x1, y1)
.Type: Point
-
width
Contains the width of the rectangle. Equals
x1 - x0
.Return type: float
-
height
Contains the height of the rectangle. Equals
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
-
Remark
A rectangle’s coordinates can also be accessed via index, e.g. r.x0 == r[0]
, and the tuple()
and list()
functions yield sequence objects of its components.
Rect Algebra
For a general background, see chapter Operator Algebra for Geometry Objects.
Examples
Example 1 - different ways of construction:
>>> p1 = fitz.Point(10, 10)
>>> p2 = fitz.Point(300, 450)
>>>
>>> fitz.Rect(p1, p2)
fitz.Rect(10.0, 10.0, 300.0, 450.0)
>>>
>>> fitz.Rect(10, 10, 300, 450)
fitz.Rect(10.0, 10.0, 300.0, 450.0)
>>>
>>> fitz.Rect(10, 10, p2)
fitz.Rect(10.0, 10.0, 300.0, 450.0)
>>>
>>> fitz.Rect(p1, 300, 450)
fitz.Rect(10.0, 10.0, 300.0, 450.0)
Example 2 - what happens during rounding:
>>> r = fitz.Rect(0.5, -0.01, 123.88, 455.123456)
>>>
>>> r
fitz.Rect(0.5, -0.009999999776482582, 123.87999725341797, 455.1234436035156)
>>>
>>> r.round() # = r.irect
fitz.IRect(0, -1, 124, 456)
Example 3 - inclusion and itersection:
>>> m = fitz.Matrix(45)
>>> r = fitz.Rect(10, 10, 410, 610)
>>> r * m
fitz.Rect(-424.2640686035156, 14.142135620117188, 282.84271240234375, 721.2489013671875)
>>>
>>> r | fitz.Point(5, 5)
fitz.Rect(5.0, 5.0, 410.0, 610.0)
>>>
>>> r + 5
fitz.Rect(15.0, 15.0, 415.0, 615.0)
>>>
>>> r & fitz.Rect(0, 0, 15, 15)
fitz.Rect(10.0, 10.0, 15.0, 15.0)
Example 4 - containment:
>>> r = fitz.Rect(...) # any rectangle
>>> ir = r.irect # its IRect version
>>> # even though you get ...
>>> ir in r
True
>>> # ... and ...
>>> r in ir
True
>>> # ... r and ir are still different types!
>>> r == ir
False
>>> # corners are always part of non-epmpty rectangles
>>> r.bottom_left in r
True
>>>
>>> # numbers are checked against coordinates
>>> r.x0 in r
True
Example 5 - create a finite copy:
Create a copy that is guarantied to be finite in two ways:
>>> r = fitz.Rect(...) # any rectangle
>>>
>>> # alternative 1
>>> s = fitz.Rect(r.top_left, r.top_left) # just a point
>>> s | r.bottom_right # s is a finite rectangle!
>>>
>>> # alternative 2
>>> s = (+r).normalize()
>>> # r.normalize() changes r itself!
Example 6 - adding a Python sequence:
Enlarge rectangle by 5 pixels in every direction:
>>> r = fitz.Rect(...)
>>> r1 = r + (-5, -5, 5, 5)
Example 7 - inline operations:
Replace a rectangle with its transformation by the inverse of a matrix-like object:
>>> r /= (1, 2, 3, 4, 5, 6)