@@ -682,6 +682,41 @@ def intersection(bbox1, bbox2):
682682class Bbox (BboxBase ):
683683"""
684684 A mutable bounding box.
685+
686+ Examples
687+ --------
688+ >>> # the default constructor takes the boundary "points" [[xmin, ymin],
689+ >>> # [xmax, ymax]]
690+ >>> unit_box = Bbox([[1, 1], [2, 2]])
691+
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)
696+
697+ >>> # and thus it overlaps with every bbox
698+ >>> assert unit_bbox.overlaps(null)
699+
700+ >>> # a union containing null (the "zero" Bbox) will always return null
701+ >>> assert null == Bbox.union([unit_bbox, null])
702+
703+ >>> # a Bbox can be created from extents (xmin, ymin, xmax, ymax)
704+ >>> assert unit_bbox == Bbox.from_extents(1, 1, 2, 2)
705+
706+ >>> # or from "bounds" (xmin, ymin, width, height)
707+ >>> assert unit_bbox == Bbox.from_bounds(1, 1, 1, 1)
708+
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)))
712+
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+
685720 """
686721
687722def __init__ (self ,points ,** kwargs ):