An algebraic take on axis-aligned rectangles.
 
This module aims to simplify working with bounding boxes.
 
 
It defines the class Rect with the following methods and attributes:
  - Two binary operators | ("join") and & ("meet").
  - Two identity elements with respect to | and &, Rect.EMPTY and Rect.PLANE.
  - Two polyadic class methods Rect.enclose(rects) and Rect.overlap(rects)
    as generalizations of | and & over arbitrary numbers of rectangles.
  - A set of operators that define containment relations between rectangles.
  - A class method Rect.enclosures(rects) that computes the bounding boxes
    for all subsets of "transitively" overlapping rectangles in a given set of
    rectangles.
 
 
The Rect class together with the | and & operations and the identity elements
form a complete lattice so that for all Rect objects a, b and c the following
laws hold:
 
 
Identity Elements:
 
    a | Rect.EMPTY  ==  a
    a & Rect.PLANE  ==  a
 
 
Absorbing Elements:
 
    a | Rect.PLANE  ==  Rect.PLANE
    a & Rect.EMPTY  ==  Rect.EMPTY
 
 
Idempotency:
 
    a | a  ==  a
    a & a  ==  a
 
 
Commutativity:
 
    a | b  ==  b | a
    a & b  ==  b & a
 
 
Associativity:
 
    (a | b) | c  ==  a | (b | c)
    (a & b) & c  ==  a & (b & c)
 
 
Absorption:
 
    a | (a & b)  ==  a
    a & (a | b)  ==  a
 
 
Since these laws already define a partially ordered set, the following laws also
hold:
 
 
Least Element:
 
    Rect.EMPTY ≦ a
 
 
Greatest Element:
 
    a ≦ Rect.PLANE
 
 
Reflexivity:
 
    a ≦ a
 
 
Transitivity:
 
    a ≦ b  and  b ≦ c   🡒   a ≦ c
 
 
Antisymmetry:
 
    a ≦ b  and  b ≦ a   🡘   a == b
 
 
Monotonicity:
 
    a1 ≦ a2  and  b1 ≦ b2   🡒   a1 | b1  ≦  a2 | b2
    a1 ≦ a2  and  b1 ≦ b2   🡒   a1 & b1  ≦  a2 & b2
 
 
Semidistributivity:
 
    (a & b) | (a & c)  ≦  a & (b | c)
    a | (b & c)  ≦  (a | b) & (a | c)
 
 
Notice the absence of the laws of distribution and modularity.
 
 
A rectangle is created like so:
 
    r = Rect(box)
 
where box is an already existing Rect object, tuple, list, iterator or other
iterable, provided it is either empty or contains/yields four numbers that
denote the left, top, right and bottom coordinates (in that order).  If box is
empty or its values are such that the resulting Rect would have negative width
or height the result will be Rect.EMPTY. Otherwise, a ValueError is raised.
 
Coordinate values increase from left to right and from top to bottom.  Therefor,
if left ≦ right and top ≦ bottom the resulting rectangle will be a Rect with the
specified coordinates.  If left > right or top > bottom the resulting rectangle
will equal Rect.EMPTY.
 
Rect objects are immutable and the properties have no setters.
 
All method results are covariant under subtyping.
 
Rect() and enclosures() accept any type of iterable.  The operators however
work reliably only on sequence-like objects, but not iterators.  If you pass an
iterator as an argument, the behavior will be undefined, probably raising an
exception, or worse, causing inexplicably wrong results.
 
Rects can be used as a drop-in in contexts where axis-aligned rectangles are
represented by 4-tuples, like e.g. Pillow's Image.crop() method. For contexts
where such rectangles are represented as pairs of point coordinates the class
method Rect.from_points() and the Rect.points property can be used.
 
 
See API documentation here:
 
https://pillmuncher.github.io/pyraxial
 
 
Here are some usage examples:
 
>>> from pyraxial import Rect
 
>>> a = Rect((1, 2, 3, 4))
 
>>> a.left, a.top, a.right, a.bottom
(1, 2, 3, 4)
 
>>> a.points
((1, 2), (3, 4))
 
>>> a.width, a.height
(2, 2)
 
>>> b = Rect((2, 3, 4, 5))
 
>>> a | b
Rect((1, 2, 4, 5))
 
>>> a & b
Rect((2, 3, 3, 4))
 
>>> a & Rect.EMPTY == Rect.EMPTY
True
 
>>> a | Rect.PLANE == Rect.PLANE
True
 
>>> a | Rect.EMPTY == a & Rect.PLANE == a
True
 
>>> rects = [Rect((1, 2, 3, 4)), Rect((2, 3, 4, 5)), Rect((3, 4, 5, 6))]
 
>>> Rect.enclose(*rects)
Rect((1, 2, 5, 6))
 
>>> Rect.overlap(*rects)
Rect((3, 4, 3, 4))
 
>>> Rect.enclose(Rect.EMPTY, *rects) == Rect.enclose(*rects)
True
 
>>> Rect.enclose(Rect.PLANE, *rects) == Rect.PLANE
True
 
>>> Rect.overlap(Rect.EMPTY, *rects) == Rect.EMPTY
True
 
>>> Rect.overlap(Rect.PLANE, *rects) == Rect.overlap(*rects)
True
 
>>> rects += [Rect((7, 8, 8, 9)), Rect((8, 7, 9, 8))]
 
>>> set(Rect.enclosures(rects)) == set(
...    [Rect((1, 2, 5, 6)), Rect((7, 7, 9, 9))])
True

Package Contents

Classes
		builtins.tuple(builtins.object) Rect   class Rect(builtins.tuple)     Rect(box)       Method resolution order: Rect builtins.tuple builtins.object Methods defined here: __and__(self, other) The meet operator.   Return the greatest rectangle that is contained in both self and other or return Rect.EMPTY, if self and other don't overlap or one of them is Rect.EMPTY.  This is also called the greatest lower bound or infimum of self and other.   r1 & r2 & ... & rn is equivalent to Rect.overlap(r1, r2, ..., rn). __eq__(self, other) Return True if self and other are rectangles with same coordinates, otherwise return False. __ge__(self, other) Return True if self contains other, otherwise return False. __gt__(self, other) Return True if self contains, but is not equal to other, otherwise return False. __hash__(self, /) Return hash(self). __le__(self, other) Return True if other contains self, otherwise return False. __lt__(self, other) Return True if other contains, but is not equal to self, otherwise return False. __mul__(self, scalar) Return a new rectangle with the coordinates multiplied by scalar.   scalar must be a number. __ne__(self, other) Return True if self and other are rectangles with different coordinates, otherwise return False. __or__(self, other) The join operator.   Return the smallest rectangle that contains both self and other or return Rect.EMPTY, if both are Rect.EMPTY.  This is also called the smallest upper bound or supremum of self and other.  In computer graphics programming this is known as the minimal bounding box of self and other.   r1 | r2 | ... | rn is equivalent to Rect.enclose(r1, r2, ..., rn). __rand__ = __and__(self, other) __repr__(self) x.__repr__() <==> repr(x) __rmul__ = __mul__(self, scalar) __ror__ = __or__(self, other) __str__(self) x.__str__() <==> str(x) move(self, offsets) Takes a pair of offsets (horizontal, vertical) and returns Rect((left+horizontal, top+vertical, right+horizontal, bottom+vertical)). Class methods defined here: enclose(*rects) from MetaRect Return the smallest rectangle that contains all rects, or Rect.EMPTY, if rects is empty.  This is also called the smallest upper bound or supremum of rects.  In computer graphics programming this is known as the minimal bounding box of rects.   If any of the rects equals Rect.PLANE, the result will also be Rect.PLANE. enclosures(rects) from MetaRect Enclose each distinct set of transitively overlapping rectangles in rects by a bounding box.   In other words, enclose each distinct set of connected rectangles. Two rectangles A and B are connected, if they either overlap or if there exists a rectangle C such that both A and B are connected to C.   Since Rect.EMPTY overlaps nothing and is overlapped by any other rect, it is always discarded.   Time complexity is O(n log n + k) with respect to the number n of distinct rects and the number k of overlaps. I hope. from_points(left_top, right_bottom) from MetaRect Takes two pairs pf numbers (left, top) and (right, bottom) and returns the rectangle Rect((left, top, right, bottom)). from_size(size) from MetaRect Takes a pair of numbers that represent the width and height of a rectangle and returns the rectangle Rect((0, 0, width, height)). overlap(*rects) from MetaRect Return the greatest rectangle that is contained in all rects, or Rect.PLANE, if rects is empty.  This is also called the greatest lower bound or infimum of rects.   If any of the rects equals Rect.EMPTY, the result will also be Rect.EMPTY. partitions(rects) from MetaRect Partition rects into distinct sets of transitively overlapping rectangles.   In other words, find all distinct sets of connected rectangles. Two rectangles A and B are connected, if they either overlap or if there exists a rectangle C such that both A and B are connected to C.   Since Rect.EMPTY overlaps nothing and is overlapped by any other rect, it is always discarded.   Time complexity is O(n log n + k) with respect to the number of distinct rects n and the number of overlaps k. I hope. Static methods defined here: __new__(cls, box) Create a new axis-aligned rectangle of type Rect from box.   box must be an iterable of either zero or four numbers.  These are taken to be the left, top, right and bottom coordinates (in that order) of the rectangle.  If box is empty or its values are such that the resulting Rect would have negative width or height the result will be Rect.EMPTY.   Raises ValueError if box is not iterable or of the wrong size. Readonly properties defined here: area The area of the rectangle. bottom The bottom coordinate of the rectangle. height The height of the rectangle. horizontal The left and right coordinates of the rectangle. left The left coordinate of the rectangle. left_bottom The left bottom coordinate of the rectangle. left_top The left top coordinate of the rectangle. points The left top and right bottom coordinates of the rectangle. right The right coordinate of the rectangle. right_bottom The right bottom coordinate of the rectangle. right_top The right top coordinate of the rectangle. size The width and height of the rectangle. top The top coordinate of the rectangle. vertical The top and bottom coordinates of the rectangle. width The width of the rectangle. Data and other attributes defined here: EMPTY = Rect(()) PLANE = Rect((-inf, -inf, inf, inf)) Methods inherited from builtins.tuple: __add__(self, value, /) Return self+value. __contains__(self, key, /) Return key in self. __getattribute__(self, name, /) Return getattr(self, name). __getitem__(self, key, /) Return self[key]. __getnewargs__(self, /) __iter__(self, /) Implement iter(self). __len__(self, /) Return len(self). count(self, value, /) Return number of occurrences of value. index(self, value, start=0, stop=9223372036854775807, /) Return first index of value.   Raises ValueError if the value is not present. Class methods inherited from builtins.tuple: __class_getitem__(...) from MetaRect See PEP 585

Data
		__all__ = ['Rect']