Clarify how get_path_collection_extents works. Add get_paths_extents as a convenience wrapper around it.

mdboom · mdboom · commit b6fd848cd1c6 · 2012-04-19T12:14:41.000-04:00
diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -710,12 +710,52 @@ def hatch(cls, hatchpattern, density=6):
         return hatch_path
 
 _get_path_collection_extents = get_path_collection_extents
-def get_path_collection_extents(*args):
+def get_path_collection_extents(
+        master_transform, paths, transforms, offsets, offset_transform):
     """
-    Given a sequence of :class:`Path` objects, returns the bounding
-    box that encapsulates all of them.
+    Given a sequence of :class:`Path` objects, :class:`Transform`
+    objects and offsets, as found in a
+    :class:`collections.PathCollection`, returns the bounding box that
+    encapsulates all of them.
+
+    *master_transform* is a global transformation to apply to all paths
+
+    *paths* is a sequence of :class:`Path` instances.
+
+    *transforms* is a sequence of :class:`Affine2D` instances.
+
+    *offsets* is a sequence of (x, y) offsets (or an Nx2 array)
+
+    *offset_transform* is a :class:`Affine2D` to apply to the offsets
+    before applying the offset to the path.
+
+    The way that *paths*, *transforms* and *offsets* are combined
+    follows the same method as for collections.  Each is iterated over
+    independently, so if you have 3 paths, 2 transforms and 1 offset,
+    their combinations are as follows:
+
+        (A, A, A), (B, B, A), (C, A, A)
     """
     from transforms import Bbox
-    if len(args[1]) == 0:
+    if len(paths) == 0:
         raise ValueError("No paths provided")
-    return Bbox.from_extents(*_get_path_collection_extents(*args))
+    return Bbox.from_extents(*_get_path_collection_extents(
+        master_transform, paths, transforms, offsets, offset_transform))
+
+def get_paths_extents(paths, transforms=[]):
+    """
+    Given a sequence of :class:`Path` objects and optional
+    :class:`Transform` objects, returns the bounding box that
+    encapsulates all of them.
+
+    *paths* is a sequence of :class:`Path` instances.
+
+    *transforms* is an optional sequence of :class:`Affine2D`
+    instances to apply to each path.
+    """
+    from transforms import Bbox, Affine2D
+    if len(paths) == 0:
+        raise ValueError("No paths provided")
+    return Bbox.from_extents(*_get_path_collection_extents(
+        Affine2D(), paths, transforms, [], Affine2D()))
+
