@@ -682,6 +682,82 @@ 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::
732+
733+ It is recommended to always specify ``ignore`` explicitly. If not, the
734+ default value of ``ignore`` can be changed at any time by code with
735+ access to your Bbox, for example using the method `~.Bbox.ignore`.
736+
737+ **Properties of the ``null`` bbox**
738+
739+ .. note::
740+
741+ The current behavior of `Bbox.null()` may be surprising as it does
742+ not have all of the properties of the "empty set", and as such does
743+ not behave like a "zero" object in the mathematical sense. We may
744+ change that in the future (with a deprecation period).
745+
746+ The null bbox is the identity for intersections
747+
748+ >>> Bbox.intersection(Bbox([[1, 1], [3, 7]]), Bbox.null())
749+ Bbox([[1.0, 1.0], [3.0, 7.0]])
750+
751+ except with itself, where it returns the full space.
752+
753+ >>> Bbox.intersection(Bbox.null(), Bbox.null())
754+ Bbox([[-inf, -inf], [inf, inf]])
755+
756+ A union containing null will always return the full space (not the other
757+ set!)
758+
759+ >>> Bbox.union([Bbox([[0, 0], [0, 0]]), Bbox.null()])
760+ Bbox([[-inf, -inf], [inf, inf]])
685761 """
686762
687763def __init__ (self ,points ,** kwargs ):
@@ -690,12 +766,6 @@ def __init__(self, points, **kwargs):
690766 ----------
691767 points : ndarray
692768 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`.
699769 """
700770BboxBase .__init__ (self ,** kwargs )
701771points = np .asarray (points ,float )