@@ -685,38 +685,60 @@ class Bbox(BboxBase):
685685
686686 Examples
687687 --------
688- >>> # the default constructor takes the boundary "points" [[xmin, ymin],
689- >>> # [xmax, ymax]]
690- >>> unit_box = Bbox([[1, 1], [2, 2]])
688+ The default constructor takes the boundary "points" ``[[xmin, ymin],
689+ [xmax, ymax]]``.
691690
692- >>> # the "zero" Bbox (i.e. "identity" object for Bbox.intersection), the
693- >>> # null bbox has (min, max) = (np.inf, -np.inf) for each dimension
694- >>> null = Bbox.null()
695- >>> assert unit_box == Bbox.intersection(unit_box, null)
691+ >>> example_box = Bbox([[1, 1], [3, 7]])
692+ >>> example_box
693+ Bbox([[1.0, 1.0], [3.0, 7.0]])
696694
697- >>> # and thus it overlaps with every bbox
698- >>> assert unit_bbox.overlaps(null)
695+ Alternatively, a Bbox can be created from the flattened array, the
696+ so-called "extents" ``(xmin, ymin, xmax, ymax)``
699697
700- >>> # a union containing null (the "zero" Bbox) will always return null
701- >>> assert null == Bbox.union([unit_bbox, null ])
698+ >>> Bbox.from_extents(1, 1, 3, 7)
699+ ([[1.0, 1.0], [3.0, 7.0] ])
702700
703- >>> # a Bbox can be created from extents (xmin, ymin, xmax, ymax)
704- >>> assert unit_bbox == Bbox.from_extents(1, 1, 2, 2)
701+ or from the "bounds" ``(xmin, ymin, width, height)``.
705702
706- >>> # or from "bounds" (xmin, ymin, width, height )
707- >>> assert unit_bbox == Bbox.from_bounds(1 , 1, 1, 1 )
703+ >>> Bbox.from_bounds(1, 1, 2, 6 )
704+ ([[1.0 , 1.0], [3.0, 7.0]] )
708705
709- >>> # or from an arbitrary list of points (here, 10 random points)
710- >>> random_bbox = Bbox.null()
711- >>> random_bbox.update_from_data_xy(np.random.rand((10, 2)))
706+ The "empty" object for accumulating Bboxs is the null bbox, which has
707+ ``(min, max) = (np.inf, -np.inf)`` for each dimension.
712708
713- >>> # to quickly update a Bbox to include new point(s), simply use
714- >>> # `ignore=False`, it's faster than using `union` directly
715- >>> new_data = np.random.rand(10, 2) # 10 new points
716- >>> new_bbox = Bbox.null()
717- >>> new_bbox.update_from_data_xy(new_data)
718- >>> assert random_bbox.update_from_data_xy(new_data, ignore=False)\
719-
709+ >>> Bbox.null()
710+ Bbox([[inf, inf], [-inf, -inf]])
711+
712+ Adding points to the null bbox will give you the bbox of those points.
713+
714+ >>> box = Bbox.null()
715+ >>> box.update_from_data_xy([[1, 1]])
716+ >>> box
717+ Bbox([[1.0, 1.0], [1.0, 1.0]])
718+ >>> box.update_from_data_xy([[2, 3], [3, 2]], ignore=False)
719+ >>> box
720+ Bbox([[1.0, 1.0], [3.0, 3.0]])
721+
722+ Setting ``ignore=True`` is equivalent to starting over from a null bbox.
723+
724+ >>> box.update_from_data_xy([[1, 1]], ignore=True)
725+ >>> box
726+ Bbox([[1.0, 1.0], [1.0, 1.0]])
727+
728+ The null bbox is also the identity for intersections
729+
730+ >>> Bbox.intersection(example_box, Bbox.null())
731+ Bbox([[1.0, 1.0], [3.0, 7.0]])
732+
733+ except with itself, where it returns the full space.
734+
735+ >>> Bbox.intersection(Bbox.null(), Bbox.null())
736+ Bbox([[-inf, -inf], [inf, inf]])
737+
738+ A union containing null will always return the full space (not null!)
739+
740+ >>> Bbox.union([example_box, Bbox.null()])
741+ Bbox([[-inf, -inf], [inf, inf]])
720742 """
721743
722744def __init__ (self ,points ,** kwargs ):
@@ -729,8 +751,8 @@ def __init__(self, points, **kwargs):
729751 Notes
730752 -----
731753 If you need to create a `Bbox` object from another form
732- of data, consider the static methods :meth:`unit`,
733- :meth:`from_bounds` and :meth:` from_extents`.
754+ of data, consider the static methods :meth:`from_bounds` and
755+ :meth:`from_extents`.
734756 """
735757BboxBase .__init__ (self ,** kwargs )
736758points = np .asarray (points ,float )