Algebra with Matrices, Rectangles and Points

For the Matrix, Rect, IRect and Point classes algebraic operations are possible to some extent. Following we will describe what they are and how they can be used. For binary operations, the type of the second operand does not need to equal that of the left operand. Adjustments take place where necessary. Usually, numeric values are also allowed, as well as lists or tuples of numbers instead of points, rectangles or matrices. In such cases, we talk of "like" objects, e.g. (2, 4) is called a point-like object.

All binary operations are also fully supported in-place.

Matrix Algebra

Matrix objects m, m1, m2 can be added, subtracted, negated, inverted, multiplied or divided. The result of these operations always is a new matrix. In addition, the "absolute value" of a matrix can be calculated - its Euclidean norm - which is a non-negative floating point number.

• m1 + m2 is defined as the matrix [m1.a + m2.a, m1.b + m2.b, ..., m1.f + m2.f]. m2 can as well be number, which is then added component-wise. Analogous is also true for the following binary operations.
• m1 - m2 analogous to addition.
• m1 * m2 is defined by m1.concat(m2), if m2 is a matrix-like object. If it is a number, component-wise multiplication takes place.
• m1 / m2 is defined by m1 * ~m2.
• -m is defined by [-m.a, -m.b, ..., -m.f].
• +m is just a copy of m.
• ~m is defined by invert(m). This means that m * ~m = ~m * m = fitz.Identity. Because we are dealing with floats here, this equality often is only almost true because of rounding effects etc. If m is not invertible (degenerate), then ~m = [0, 0, 0, 0, 0, 0].
• abs(m) is defined by math.sqrt(m.a**2 + m.b**2 + ... + m.f**2).
• bool(m) is False if m = fitz.Matrix(0, 0, 0, 0, 0, 0), else True.
• Comparisons are based on components, not object identities: m1 == m2 is True if all components are equal. Note however, that floating point values are compared here: therefore a false inequality may result from e.g. rounding effects.
• In-place operators are fully supperted: m1 /= (1, 2, 3, 4, 5, 6) for example calculates the inverse of fitz.Matrix(1,2,3,4,5,6) and multiplies the result into m1.

Following are some examples to illustrate the above.

• check if a matrix is invertible: if not bool(~m): print("m is not invertible")
• check whether two matrices are (almost) equal: if abs(m1 - m2) < epsilon: print("m1 (almost) equals m2")
• do a complex matrix calculation: m = m1*(m2 + ~m3)*m4
• divide components by 2: m /= 2.

Rectangle Algebra

Rect and IRect objects can be added and subtracted to / from other rectangle-like obects or numbers, they can be negated and multiplied with matrix-like objects or numbers. In addition, inclusion | and intersection & of rectangles with other objects are supported as binary operations. The result of these operations always is a new rectangle with the same type (Rect or IRect) as the left operand.

As with matrices, in-place operators are fully supported.

• r1 + r2 and r1 - r2 are defined component-wise as with matrices. Any of the two operands can be a Rect or an IRect. In addition, r2 can also be a number or rectangle-like.
• -r is defined component-wise (Rect or IRect).
• +r is a copy of r.
• r * m is a new rectangle resulting from r transformed with matrix-like m. If m is a number, it is multiplied with the coordinates.
• r / m is analogous to multiplication. If m is matrix-like, then its inverse is multiplied with r.
• r1 | r2 (inclusion) is the smallest rectangle containing both, r1 (rectangle) and r2 (rectangle-like or point-like).
• r1 & r2 (intersection) is the largest rectangle that is contained in both, r1 (rectangle) and r2 (rectangle-like).
• bool(r) is False if all components of r are zero, else True.

Example ("rectangle hull"):

If plist = [p0, p1, ..., pn] is a list of Point objects then r computed by

r = fitz.Rect(p0, p0)
for p in plist:
    r = r | p

is the smallest rectangle containing all points in the list. Note: if you want an IRect perform a r.round() afterwards.

Example ("finite rectangle"):

MuPDF defines rectangles as infinite, if the bottom right corner is not south-eastern to the top left one. This may be awkward sometimes. So, here is a recipe to create a finite rectangle covering the same area:

r = fitz.Rect(...)      # potentially infinite rectangle
s = fitz.Rect(r.top_left, r.top_left)   # rect containing just a point
s = s | r.bottom_right  # s now is a finite rectangle

A simpler method is r.normalize(). This converts the rectangle to its finite version. To leave it intact, create a finite copy like this:

s = (+r).normalize()

Point Algebra

Point objects can be added, subtracted and negated just like rectangles, yielding new point objects.

• p1 + p2, p1 - p2, -p, +p are defined component-wise like the rectangle operations. p2 can be point-like or a number.
• abs(p) is the Eucldean norm math.sqrt(p.x**2 + p.y**2) as with matrices.
• p * m is a new point resulting from p transformed with a matrix-like m or a number. Instead of p * ~m you can also write p / m if m is matrix-like.
• In-place operators are also fully supported: if p = fitz.Point(100, 100), then p /= (1, 2, 3, 4, 5, 6) delivers fitz.Point(-49.0, 48.0), and p /= 2 is fitz.Point(50.0, 50.0).