matplotlib
diff --git a/‎lib/matplotlib/hatch.py
Copy file name to clipboardExpand all lines: lib/matplotlib/hatch.py
+178-36Lines changed: 178 additions & 36 deletions b/‎lib/matplotlib/hatch.py
Copy file name to clipboardExpand all lines: lib/matplotlib/hatch.py
+178-36Lines changed: 178 additions & 36 deletions
@@ -2,7 +2,7 @@
 
 import numpy as np
 
-from matplotlib import cbook
+from matplotlib import _api
 from matplotlib.path import Path
 
 
@@ -186,46 +186,188 @@ def __init__(self, hatch, density):
     ]
 
 
-def _validate_hatch_pattern(hatch):
-    valid_hatch_patterns = set(r'-+|/\xXoO.*')
-    if hatch is not None:
-        invalids = set(hatch).difference(valid_hatch_patterns)
-        if invalids:
-            valid = ''.join(sorted(valid_hatch_patterns))
-            invalids = ''.join(sorted(invalids))
-            cbook.warn_deprecated(
-                '3.4',
-                message=f'hatch must consist of a string of "{valid}" or '
-                        'None, but found the following invalid values '
-                        f'"{invalids}". Passing invalid values is deprecated '
-                        'since %(since)s and will become an error %(removal)s.'
-            )
+class Hatch:
+    r"""
+    Pattern to be tiled within a filled area.
+
+    For a visual example of the available *Hatch* patterns, `view these docs
+    online <Hatch>` or run `Hatch.demo`.
+
+    When making plots that contain multiple filled shapes, like :doc:`bar
+    charts </gallery/lines_bars_and_markers/bar_stacked>` or filled
+    :doc:`countour plots </images_contours_and_fields/contourf_hatching>`, it
+    is common to use :doc:`color </tutorials/colors/colors>` to distinguish
+    between areas. However, if color is not available, such as when printing in
+    black and white, Matplotlib also supports hatching (i.e. filling each
+    area with a unique repeating pattern or lines or shapes) in order to make
+    it easy to refer to a specific filled bar, shape, or similar.
+
+    .. warning::
+        Hatching is currently only supported in the Agg, PostScript, PDF, and
+        SVG backends.
+
+    **Hatching patterns**
+
+    There hatching primitives built into Matplotlib are:
+
+    .. rst-class:: value-list
+
+        '-'
+            Horizontal lines.
+        '|'
+            Vertical lines.
+        '+'
+            Crossed lines. ``'+'`` is equivalent to ``'-|'``.
+        '\'
+            Diagonal lines running northwest to southeast.
+        '/'
+            Diagonal lines running southwest to northeast.
+        'x'
+            Crossed diagonal lines. Equivalent to ``r'\/'``.
+        'X'
+            Synonym for ``'x'``.
+        '.'
+            Dots (i.e. very small, filled circles).
+        'o'
+            Small, unfilled circles.
+        'O'
+            Large, unfilled circles.
+        '*'
+            Filled star shape.
+
+    Hatching primitives can be combined to make more complicated patterns. For
+    example, a hatch pattern of '*/|' would fill the area with vertical and
+    diagonal lines as well as stars.
+
+    **Hatching Density**
+
+    By default, the hatching pattern is tiled so that there are **6** lines per
+    inch (in display space), but this can be tuned (in integer increments)
+    using the *density* kwarg to *Hatch*.
+
+    For convenience, the same symbol can also be repeated to request a higher
+    hatching density. For example, ``'||-'`` will have twice as many vertical
+    lines as ``'|-'``.  Notice that since ``'|-'`` can also be written as
+    ``'+'``, we can also write ``'||-'`` as ``'|+'``.
+
+    Examples
+    --------
+    For more examples of how to use hatching, see `the hatching demo
+    </gallery/shapes_and_collections/hatch_demo>` and `the contourf hatching
+    demo </gallery/images_contours_and_fields/contourf_hatching>`.
+
+    .. plot::
+        :alt: Demo showing each hatching primitive at its default density.
+
+        from matplotlib.hatch import Hatch
+        Hatch.demo()
+    """
+
+    _valid_hatch_patterns = set(r'-|+/\xX.oO*')
+
+    def __init__(self, pattern_spec, density=6):
+        self.density = density
+        self._pattern_spec = pattern_spec
+        self.patterns = self._validate_hatch_pattern(pattern_spec)
+        self._build_path()
+
+    @classmethod
+    def from_path(cls, path):
+        hatch = cls(None, 0)
+        hatch.path = path
 
+    def _build_path(self):
+        num_vertices = sum([pattern.num_vertices for pattern in self.patterns])
 
+        if num_vertices == 0:
+            return Path(np.empty((0, 2)))
+
+        vertices = np.empty((num_vertices, 2))
+        codes = np.empty(num_vertices, Path.code_type)
+
+        cursor = 0
+        for pattern in self.patterns:
+            if pattern.num_vertices != 0:
+                vertices_chunk = vertices[cursor:cursor + pattern.num_vertices]
+                codes_chunk = codes[cursor:cursor + pattern.num_vertices]
+                pattern.set_vertices_and_codes(vertices_chunk, codes_chunk)
+                cursor += pattern.num_vertices
+
+        self.path = Path(vertices, codes)
+
+    def _validate_hatch_pattern(self, patterns):
+        if patterns is None:
+            return []
+        elif isinstance(patterns, str):
+            invalids = set(patterns).difference(Hatch._valid_hatch_patterns)
+            if invalids:
+                Hatch._warn_invalid_hatch(invalids)
+            return [hatch_type(patterns, self.density)
+                    for hatch_type in _hatch_types]
+        elif np.all([isinstance(p, HatchPatternBase) for p in patterns]):
+            return patterns
+        else:
+            raise ValueError(f"Cannot construct hatch pattern from {patterns}")
+
+    def _warn_invalid_hatch(invalids):
+        valid = ''.join(sorted(Hatch._valid_hatch_patterns))
+        invalids = ''.join(sorted(invalids))
+        _api.warn_deprecated(
+            '3.4',
+            message=f'hatch must consist of a string of "{valid}" or None, '
+                    f'but found the following invalid values "{invalids}". '
+                    'Passing invalid values is deprecated since %(since)s and '
+                    'will become an error %(removal)s.'
+        )
+
+    @staticmethod
+    def demo(density=6):
+        import matplotlib.pyplot as plt
+        from matplotlib.patches import Rectangle
+        fig = plt.figure()
+        ax = fig.add_axes([0, 0, 1, 1])
+        ax.set_axis_off()
+        num_patches = len(Hatch._valid_hatch_patterns)
+
+        spacing = 0.1  # percent of width
+        boxes_per_row = 4
+        num_rows = np.ceil(num_patches / boxes_per_row)
+        inter_box_dist_y = 1/num_rows
+        posts = np.linspace(0, 1, boxes_per_row + 1)
+        inter_box_dist_x = posts[1] - posts[0]
+        font_size = 12
+        fig_size = (4, 4)
+        text_pad = 0.2  # fraction of text height
+        text_height = (1 + text_pad)*(
+            fig.dpi_scale_trans + ax.transAxes.inverted()
+        ).transform([1, 1])[1]
+        # half of text pad
+        bottom_padding = text_height*(1 - (1/(1+text_pad)))/2
+
+        for i, hatch in enumerate(Hatch._valid_hatch_patterns):
+            row = int(i/boxes_per_row)
+            col = i - row*boxes_per_row
+            ax.add_patch(Rectangle(
+                xy=[(col + spacing/2) * inter_box_dist_x,
+                    bottom_padding + row*inter_box_dist_y],
+                width=inter_box_dist_x*(1 - spacing),
+                height=inter_box_dist_y*(1 - text_height),
+                transform=ax.transAxes,
+                hatch=hatch,
+                label="'" + hatch + "'"
+            ))
+            ax.text((col + 1/2) * inter_box_dist_x,
+                    bottom_padding + (-text_height*(1/(1+text_pad)) + row
+                    + 1)*inter_box_dist_y,
+                    "'" + hatch + "'", horizontalalignment='center',
+                    fontsize=font_size)
+
+
+@_api.deprecated("3.4")
 def get_path(hatchpattern, density=6):
     """
     Given a hatch specifier, *hatchpattern*, generates Path to render
     the hatch in a unit square.  *density* is the number of lines per
     unit square.
     """
-    density = int(density)
-
-    patterns = [hatch_type(hatchpattern, density)
-                for hatch_type in _hatch_types]
-    num_vertices = sum([pattern.num_vertices for pattern in patterns])
-
-    if num_vertices == 0:
-        return Path(np.empty((0, 2)))
-
-    vertices = np.empty((num_vertices, 2))
-    codes = np.empty(num_vertices, Path.code_type)
-
-    cursor = 0
-    for pattern in patterns:
-        if pattern.num_vertices != 0:
-            vertices_chunk = vertices[cursor:cursor + pattern.num_vertices]
-            codes_chunk = codes[cursor:cursor + pattern.num_vertices]
-            pattern.set_vertices_and_codes(vertices_chunk, codes_chunk)
-            cursor += pattern.num_vertices
-
-    return Path(vertices, codes)
+    return Hatch(hatchpattern).path