@@ -682,6 +682,80 @@ def intersection(bbox1, bbox2):
682682class Bbox (BboxBase ):
683683"""
684684 A mutable bounding box.
685+
686+ Examples
687+ --------
688+ **Create from known bounds**
689+
690+ The default constructor takes the boundary "points" ``[[xmin, ymin],
691+ [xmax, ymax]]``.
692+
693+ >>> Bbox([[1, 1], [3, 7]])
694+ Bbox([[1.0, 1.0], [3.0, 7.0]])
695+
696+ Alternatively, a Bbox can be created from the flattened points array, the
697+ so-called "extents" ``(xmin, ymin, xmax, ymax)``
698+
699+ >>> Bbox.from_extents(1, 1, 3, 7)
700+ Bbox([[1.0, 1.0], [3.0, 7.0]])
701+
702+ or from the "bounds" ``(xmin, ymin, width, height)``.
703+
704+ >>> Bbox.from_bounds(1, 1, 2, 6)
705+ Bbox([[1.0, 1.0], [3.0, 7.0]])
706+
707+ **Create from collections of points**
708+
709+ The "empty" object for accumulating Bboxs is the null bbox, which is a
710+ stand-in for the empty set.
711+
712+ >>> Bbox.null()
713+ Bbox([[inf, inf], [-inf, -inf]])
714+
715+ Adding points to the null bbox will give you the bbox of those points.
716+
717+ >>> box = Bbox.null()
718+ >>> box.update_from_data_xy([[1, 1]])
719+ >>> box
720+ Bbox([[1.0, 1.0], [1.0, 1.0]])
721+ >>> box.update_from_data_xy([[2, 3], [3, 2]], ignore=False)
722+ >>> box
723+ Bbox([[1.0, 1.0], [3.0, 3.0]])
724+
725+ Setting ``ignore=True`` is equivalent to starting over from a null bbox.
726+
727+ >>> box.update_from_data_xy([[1, 1]], ignore=True)
728+ >>> box
729+ Bbox([[1.0, 1.0], [1.0, 1.0]])
730+
731+ .. warning:: It is recommended to always specify ``ignore`` explicitly.
732+ If not, the default value of ``ignore`` can be changed at any time by code
733+ with access to your Bbox, for example using the method `~.Bbox.ignore`.
734+
735+ **Properties of the ``null`` bbox**
736+
737+ .. note::
738+
739+ The current behavior of `Bbox.null()` may be surprising as it does
740+ not have all of the properties of the "empty set", and as such does
741+ not behave like a "zero" object in the mathematical sense. We may
742+ change that in the future (with a deprecation period).
743+
744+ The null bbox is the identity for intersections
745+
746+ >>> Bbox.intersection(Bbox([[1, 1], [3, 7]]), Bbox.null())
747+ Bbox([[1.0, 1.0], [3.0, 7.0]])
748+
749+ except with itself, where it returns the full space.
750+
751+ >>> Bbox.intersection(Bbox.null(), Bbox.null())
752+ Bbox([[-inf, -inf], [inf, inf]])
753+
754+ A union containing null will always return the full space (not the other
755+ set!)
756+
757+ >>> Bbox.union([Bbox([[0, 0], [0, 0]]), Bbox.null()])
758+ Bbox([[-inf, -inf], [inf, inf]])
685759 """
686760
687761def __init__ (self ,points ,** kwargs ):
@@ -690,12 +764,6 @@ def __init__(self, points, **kwargs):
690764 ----------
691765 points : ndarray
692766 A 2x2 numpy array of the form ``[[x0, y0], [x1, y1]]``.
693-
694- Notes
695- -----
696- If you need to create a `Bbox` object from another form
697- of data, consider the static methods :meth:`unit`,
698- :meth:`from_bounds` and :meth:`from_extents`.
699767 """
700768BboxBase .__init__ (self ,** kwargs )
701769points = np .asarray (points ,float )