text: """
  Classes for the efficient drawing of large collections of objects that
  share most properties, e.g., a large number of line segments or
  polygons.
  
  The classes are not meant to be as flexible as their single element
  counterparts (e.g., you may not be able to select all line styles) but
  they are meant to be fast for common use cases (e.g., a large set of solid
  line segments).
  """
  
  import inspect
  import math
  from numbers import Number
  import warnings
  
  import numpy as np
  
  import matplotlib as mpl
  from . import (_api, _path, artist, cbook, cm, colors as mcolors, docstring,
                 hatch as mhatch, lines as mlines, path as mpath, transforms)
  from ._enums import JoinStyle, CapStyle
  
  
  # "color" is excluded; it is a compound setter, and its docstring differs
  # in LineCollection.
  @cbook._define_aliases({
      "antialiased": ["antialiaseds", "aa"],
      "edgecolor": ["edgecolors", "ec"],
      "facecolor": ["facecolors", "fc"],
      "linestyle": ["linestyles", "dashes", "ls"],
      "linewidth": ["linewidths", "lw"],
  })
  class Collection(artist.Artist, cm.ScalarMappable):
      r"""
      Base class for Collections. Must be subclassed to be usable.
  
      A Collection represents a sequence of `.Patch`\es that can be drawn
      more efficiently together than individually. For example, when a single
      path is being drawn repeatedly at different offsets, the renderer can
      typically execute a ``draw_marker()`` call much more efficiently than a
      series of repeated calls to ``draw_path()`` with the offsets put in
      one-by-one.
  
      Most properties of a collection can be configured per-element. Therefore,
      Collections have "plural" versions of many of the properties of a `.Patch`
      (e.g. `.Collection.get_paths` instead of `.Patch.get_path`). Exceptions are
      the *zorder*, *hatch*, *pickradius*, *capstyle* and *joinstyle* properties,
      which can only be set globally for the whole collection.
  
      Besides these exceptions, all properties can be specified as single values
      (applying to all elements) or sequences of values. The property of the
      ``i``\th element of the collection is::
  
        prop[i % len(prop)]
  
      Each Collection can optionally be used as its own `.ScalarMappable` by
      passing the *norm* and *cmap* parameters to its constructor. If the
      Collection's `.ScalarMappable` matrix ``_A`` has been set (via a call
      to `.Collection.set_array`), then at draw time this internal scalar
      mappable will be used to set the ``facecolors`` and ``edgecolors``,
      ignoring those that were manually passed in.
      """
      _offsets = np.zeros((0, 2))
      #: Either a list of 3x3 arrays or an Nx3x3 array (representing N
      #: transforms), suitable for the `all_transforms` argument to
      #: `~matplotlib.backend_bases.RendererBase.draw_path_collection`;
      #: each 3x3 array is used to initialize an
      #: `~matplotlib.transforms.Affine2D` object.
      #: Each kind of collection defines this based on its arguments.
      _transforms = np.empty((0, 3, 3))
  
      # Whether to draw an edge by default.  Set on a
      # subclass-by-subclass basis.
      _edge_default = False
  
      @docstring.interpd
      def __init__(self,
                   edgecolors=None,
                   facecolors=None,
                   linewidths=None,
                   linestyles='solid',
                   capstyle=None,
                   joinstyle=None,
                   antialiaseds=None,
                   offsets=None,
                   transOffset=None,
                   norm=None,  # optional for ScalarMappable
                   cmap=None,  # ditto
                   pickradius=5.0,
                   hatch=None,
                   urls=None,
                   *,
                   zorder=1,
                   **kwargs
                   ):
          """
          Parameters
          ----------
          edgecolors : color or list of colors, default: :rc:`patch.edgecolor`
              Edge color for each patch making up the collection. The special
              value 'face' can be passed to make the edgecolor match the
              facecolor.
          facecolors : color or list of colors, default: :rc:`patch.facecolor`
              Face color for each patch making up the collection.
          linewidths : float or list of floats, default: :rc:`patch.linewidth`
              Line width for each patch making up the collection.
          linestyles : str or tuple or list thereof, default: 'solid'
              Valid strings are ['solid', 'dashed', 'dashdot', 'dotted', '-',
              '--', '-.', ':']. Dash tuples should be of the form::
  
                  (offset, onoffseq),
  
              where *onoffseq* is an even length tuple of on and off ink lengths
              in points. For examples, see
              :doc:`/gallery/lines_bars_and_markers/linestyles`.
          capstyle : `.CapStyle`-like, default: :rc:`patch.capstyle`
              Style to use for capping lines for all paths in the collection.
              Allowed values are %(CapStyle)s.
          joinstyle : `.JoinStyle`-like, default: :rc:`patch.joinstyle`
              Style to use for joining lines for all paths in the collection.
              Allowed values are %(JoinStyle)s.
          antialiaseds : bool or list of bool, default: :rc:`patch.antialiased`
              Whether each patch in the collection should be drawn with
              antialiasing.
          offsets : (float, float) or list thereof, default: (0, 0)
              A vector by which to translate each patch after rendering (default
              is no translation). The translation is performed in screen (pixel)
              coordinates (i.e. after the Artist's transform is applied).
          transOffset : `~.transforms.Transform`, default: `.IdentityTransform`
              A single transform which will be applied to each *offsets* vector
              before it is used.
          norm : `~.colors.Normalize`, optional
              Forwarded to `.ScalarMappable`. The default of
              ``None`` means that the first draw call will set ``vmin`` and
              ``vmax`` using the minimum and maximum values of the data.
          cmap : `~.colors.Colormap`, optional
              Forwarded to `.ScalarMappable`. The default of
              ``None`` will result in :rc:`image.cmap` being used.
          hatch : str, optional
              Hatching pattern to use in filled paths, if any. Valid strings are
              ['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*']. See
              :doc:`/gallery/shapes_and_collections/hatch_style_reference` for
              the meaning of each hatch type.
          pickradius : float, default: 5.0
              If ``pickradius <= 0``, then `.Collection.contains` will return
              ``True`` whenever the test point is inside of one of the polygons
              formed by the control points of a Path in the Collection. On the
              other hand, if it is greater than 0, then we instead check if the
              test point is contained in a stroke of width ``2*pickradius``
              following any of the Paths in the Collection.
          urls : list of str, default: None
              A URL for each patch to link to once drawn. Currently only works
              for the SVG backend. See :doc:`/gallery/misc/hyperlinks_sgskip` for
              examples.
          zorder : float, default: 1
              The drawing order, shared by all Patches in the Collection. See
              :doc:`/gallery/misc/zorder_demo` for all defaults and examples.
          """
          artist.Artist.__init__(self)
          cm.ScalarMappable.__init__(self, norm, cmap)
          # list of un-scaled dash patterns
          # this is needed scaling the dash pattern by linewidth
          self._us_linestyles = [(0, None)]
          # list of dash patterns
          self._linestyles = [(0, None)]
          # list of unbroadcast/scaled linewidths
          self._us_lw = [0]
          self._linewidths = [0]
          # Flags set by _set_mappable_flags: are colors from mapping an array?
          self._face_is_mapped = None
          self._edge_is_mapped = None
          self._mapped_colors = None  # calculated in update_scalarmappable
          self._hatch_color = mcolors.to_rgba(mpl.rcParams['hatch.color'])
          self.set_facecolor(facecolors)
          self.set_edgecolor(edgecolors)
          self.set_linewidth(linewidths)
          self.set_linestyle(linestyles)
          self.set_antialiased(antialiaseds)
          self.set_pickradius(pickradius)
          self.set_urls(urls)
          self.set_hatch(hatch)
          self._offset_position = "screen"
          self.set_zorder(zorder)
  
          if capstyle:
              self.set_capstyle(capstyle)
          else:
              self._capstyle = None
  
          if joinstyle:
              self.set_joinstyle(joinstyle)
          else:
              self._joinstyle = None
  
          # default to zeros
          self._offsets = np.zeros((1, 2))
  
          if offsets is not None:
              offsets = np.asanyarray(offsets, float)
              # Broadcast (2,) -> (1, 2) but nothing else.
              if offsets.shape == (2,):
                  offsets = offsets[None, :]
              self._offsets = offsets
          elif transOffset is not None:
              _api.warn_deprecated(
                  '3.5',
                  removal='3.6',
                  message='Passing *transOffset* without *offsets* has no '
                          'effect. This behavior is deprecated since %(since)s '
                          'and %(removal)s, *transOffset* will begin having an '
                          'effect regardless of *offsets*. In the meantime, if '
                          'you wish to set *transOffset*, call '
                          'collection.set_offset_transform(transOffset) '
                          'explicitly.')
              transOffset = None
  
          self._transOffset = transOffset
  
          self._path_effects = None
          self.update(kwargs)
          self._paths = None
  
      def get_paths(self):
          return self._paths
  
      def set_paths(self):
          raise NotImplementedError
  
      def get_transforms(self):
          return self._transforms
  
      def get_offset_transform(self):
          """Return the `.Transform` instance used by this artist offset."""
          if self._transOffset is None:
              self._transOffset = transforms.IdentityTransform()
          elif (not isinstance(self._transOffset, transforms.Transform)
                and hasattr(self._transOffset, '_as_mpl_transform')):
              self._transOffset = self._transOffset._as_mpl_transform(self.axes)
          return self._transOffset
  
      def set_offset_transform(self, transOffset):
          """
          Set the artist offset transform.
  
          Parameters
          ----------
          transOffset : `.Transform`
          """
          self._transOffset = transOffset
  
      def get_datalim(self, transData):
          # Calculate the data limits and return them as a `.Bbox`.
          #
          # This operation depends on the transforms for the data in the
          # collection and whether the collection has offsets:
          #
          # 1. offsets = None, transform child of transData: use the paths for
          # the automatic limits (i.e. for LineCollection in streamline).
          # 2. offsets != None: offset_transform is child of transData:
          #
          #    a. transform is child of transData: use the path + offset for
          #       limits (i.e for bar).
          #    b. transform is not a child of transData: just use the offsets
          #       for the limits (i.e. for scatter)
          #
          # 3. otherwise return a null Bbox.
  
          transform = self.get_transform()
          transOffset = self.get_offset_transform()
          hasOffsets = np.any(self._offsets)  # True if any non-zero offsets
          if hasOffsets and not transOffset.contains_branch(transData):
              # if there are offsets but in some coords other than data,
              # then don't use them for autoscaling.
              return transforms.Bbox.null()
          offsets = self._offsets
  
          paths = self.get_paths()
  
          if not transform.is_affine:
              paths = [transform.transform_path_non_affine(p) for p in paths]
              # Don't convert transform to transform.get_affine() here because
              # we may have transform.contains_branch(transData) but not
              # transforms.get_affine().contains_branch(transData).  But later,
              # be careful to only apply the affine part that remains.
  
          if isinstance(offsets, np.ma.MaskedArray):
              offsets = offsets.filled(np.nan)
              # get_path_collection_extents handles nan but not masked arrays
  
          if len(paths) and len(offsets):
              if any(transform.contains_branch_seperately(transData)):
                  # collections that are just in data units (like quiver)
                  # can properly have the axes limits set by their shape +
                  # offset.  LineCollections that have no offsets can
                  # also use this algorithm (like streamplot).
                  return mpath.get_path_collection_extents(
                      transform.get_affine() - transData, paths,
                      self.get_transforms(),
                      transOffset.transform_non_affine(offsets),
                      transOffset.get_affine().frozen())
              if hasOffsets:
                  # this is for collections that have their paths (shapes)
                  # in physical, axes-relative, or figure-relative units
                  # (i.e. like scatter). We can't uniquely set limits based on
                  # those shapes, so we just set the limits based on their
                  # location.
  
                  offsets = (transOffset - transData).transform(offsets)
                  # note A-B means A B^{-1}
                  offsets = np.ma.masked_invalid(offsets)
                  if not offsets.mask.all():
                      bbox = transforms.Bbox.null()
                      bbox.update_from_data_xy(offsets)
                      return bbox
          return transforms.Bbox.null()
  
      def get_window_extent(self, renderer):
          # TODO: check to ensure that this does not fail for
          # cases other than scatter plot legend
          return self.get_datalim(transforms.IdentityTransform())
  
      def _prepare_points(self):
          # Helper for drawing and hit testing.
  
          transform = self.get_transform()
          transOffset = self.get_offset_transform()
          offsets = self._offsets
          paths = self.get_paths()
  
          if self.have_units():
              paths = []
              for path in self.get_paths():
                  vertices = path.vertices
                  xs, ys = vertices[:, 0], vertices[:, 1]
                  xs = self.convert_xunits(xs)
                  ys = self.convert_yunits(ys)
                  paths.append(mpath.Path(np.column_stack([xs, ys]), path.codes))
              if offsets.size:
                  xs = self.convert_xunits(offsets[:, 0])
                  ys = self.convert_yunits(offsets[:, 1])
                  offsets = np.column_stack([xs, ys])
  
          if not transform.is_affine:
              paths = [transform.transform_path_non_affine(path)
                       for path in paths]
              transform = transform.get_affine()
          if not transOffset.is_affine:
              offsets = transOffset.transform_non_affine(offsets)
              # This might have changed an ndarray into a masked array.
              transOffset = transOffset.get_affine()
  
          if isinstance(offsets, np.ma.MaskedArray):
              offsets = offsets.filled(np.nan)
              # Changing from a masked array to nan-filled ndarray
              # is probably most efficient at this point.
  
          return transform, transOffset, offsets, paths
  
      @artist.allow_rasterization
      def draw(self, renderer):
          if not self.get_visible():
              return
          renderer.open_group(self.__class__.__name__, self.get_gid())
  
          self.update_scalarmappable()
  
          transform, transOffset, offsets, paths = self._prepare_points()
  
          gc = renderer.new_gc()
          self._set_gc_clip(gc)
          gc.set_snap(self.get_snap())
  
          if self._hatch:
              gc.set_hatch(self._hatch)
              gc.set_hatch_color(self._hatch_color)
  
          if self.get_sketch_params() is not None:
              gc.set_sketch_params(*self.get_sketch_params())
  
          if self.get_path_effects():
              from matplotlib.patheffects import PathEffectRenderer
              renderer = PathEffectRenderer(self.get_path_effects(), renderer)
  
          # If the collection is made up of a single shape/color/stroke,
          # it can be rendered once and blitted multiple times, using
          # `draw_markers` rather than `draw_path_collection`.  This is
          # *much* faster for Agg, and results in smaller file sizes in
          # PDF/SVG/PS.
  
          trans = self.get_transforms()
          facecolors = self.get_facecolor()
          edgecolors = self.get_edgecolor()
          do_single_path_optimization = False
          if (len(paths) == 1 and len(trans) <= 1 and
                  len(facecolors) == 1 and len(edgecolors) == 1 and
                  len(self._linewidths) == 1 and
                  all(ls[1] is None for ls in self._linestyles) and
                  len(self._antialiaseds) == 1 and len(self._urls) == 1 and
                  self.get_hatch() is None):
              if len(trans):
                  combined_transform = transforms.Affine2D(trans[0]) + transform
              else:
                  combined_transform = transform
              extents = paths[0].get_extents(combined_transform)
              if (extents.width < self.figure.bbox.width
                      and extents.height < self.figure.bbox.height):
                  do_single_path_optimization = True
  
          if self._joinstyle:
              gc.set_joinstyle(self._joinstyle)
  
          if self._capstyle:
              gc.set_capstyle(self._capstyle)
  
          if do_single_path_optimization:
              gc.set_foreground(tuple(edgecolors[0]))
              gc.set_linewidth(self._linewidths[0])
              gc.set_dashes(*self._linestyles[0])
              gc.set_antialiased(self._antialiaseds[0])
              gc.set_url(self._urls[0])
              renderer.draw_markers(
                  gc, paths[0], combined_transform.frozen(),
                  mpath.Path(offsets), transOffset, tuple(facecolors[0]))
          else:
              renderer.draw_path_collection(
                  gc, transform.frozen(), paths,
                  self.get_transforms(), offsets, transOffset,
                  self.get_facecolor(), self.get_edgecolor(),
                  self._linewidths, self._linestyles,
                  self._antialiaseds, self._urls,
                  self._offset_position)
  
          gc.restore()
          renderer.close_group(self.__class__.__name__)
          self.stale = False
  
      def set_pickradius(self, pr):
          """
          Set the pick radius used for containment tests.
  
          Parameters
          ----------
          pr : float
              Pick radius, in points.
          """
          self._pickradius = pr
  
      def get_pickradius(self):
          return self._pickradius
  
      def contains(self, mouseevent):
          """
          Test whether the mouse event occurred in the collection.
  
          Returns ``bool, dict(ind=itemlist)``, where every item in itemlist
          contains the event.
          """
          inside, info = self._default_contains(mouseevent)
          if inside is not None:
              return inside, info
  
          if not self.get_visible():
              return False, {}
  
          pickradius = (
              float(self._picker)
              if isinstance(self._picker, Number) and
                 self._picker is not True  # the bool, not just nonzero or 1
              else self._pickradius)
  
          if self.axes:
              self.axes._unstale_viewLim()
  
          transform, transOffset, offsets, paths = self._prepare_points()
  
          # Tests if the point is contained on one of the polygons formed
          # by the control points of each of the paths. A point is considered
          # "on" a path if it would lie within a stroke of width 2*pickradius
          # following the path. If pickradius <= 0, then we instead simply check
          # if the point is *inside* of the path instead.
          ind = _path.point_in_path_collection(
              mouseevent.x, mouseevent.y, pickradius,
              transform.frozen(), paths, self.get_transforms(),
              offsets, transOffset, pickradius <= 0,
              self._offset_position)
  
          return len(ind) > 0, dict(ind=ind)
  
      def set_urls(self, urls):
          """
          Parameters
          ----------
          urls : list of str or None
  
          Notes
          -----
          URLs are currently only implemented by the SVG backend. They are
          ignored by all other backends.
          """
          self._urls = urls if urls is not None else [None]
          self.stale = True
  
      def get_urls(self):
          """
          Return a list of URLs, one for each element of the collection.
  
          The list contains *None* for elements without a URL. See
          :doc:`/gallery/misc/hyperlinks_sgskip` for an example.
          """
          return self._urls
  
      def set_hatch(self, hatch):
          r"""
          Set the hatching pattern
  
          *hatch* can be one of::
  
            /   - diagonal hatching
            \   - back diagonal
            |   - vertical
            -   - horizontal
            +   - crossed
            x   - crossed diagonal
            o   - small circle
            O   - large circle
            .   - dots
            *   - stars
  
          Letters can be combined, in which case all the specified
          hatchings are done.  If same letter repeats, it increases the
          density of hatching of that pattern.
  
          Hatching is supported in the PostScript, PDF, SVG and Agg
          backends only.
  
          Unlike other properties such as linewidth and colors, hatching
          can only be specified for the collection as a whole, not separately
          for each member.
  
          Parameters
          ----------
          hatch : {'/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
          """
          # Use validate_hatch(list) after deprecation.
          mhatch._validate_hatch_pattern(hatch)
          self._hatch = hatch
          self.stale = True
  
      def get_hatch(self):
          """Return the current hatching pattern."""
          return self._hatch
  
      def set_offsets(self, offsets):
          """
          Set the offsets for the collection.
  
          Parameters
          ----------
          offsets : (N, 2) or (2,) array-like
          """
          offsets = np.asanyarray(offsets, float)
          if offsets.shape == (2,):  # Broadcast (2,) -> (1, 2) but nothing else.
              offsets = offsets[None, :]
          self._offsets = offsets
          self.stale = True
  
      def get_offsets(self):
          """Return the offsets for the collection."""
          return self._offsets
  
      def _get_default_linewidth(self):
          # This may be overridden in a subclass.
          return mpl.rcParams['patch.linewidth']  # validated as float
  
      def set_linewidth(self, lw):
          """
          Set the linewidth(s) for the collection.  *lw* can be a scalar
          or a sequence; if it is a sequence the patches will cycle
          through the sequence
  
          Parameters
          ----------
          lw : float or list of floats
          """
          if lw is None:
              lw = self._get_default_linewidth()
          # get the un-scaled/broadcast lw
          self._us_lw = np.atleast_1d(np.asarray(lw))
  
          # scale all of the dash patterns.
          self._linewidths, self._linestyles = self._bcast_lwls(
              self._us_lw, self._us_linestyles)
          self.stale = True
  
      def set_linestyle(self, ls):
          """
          Set the linestyle(s) for the collection.
  
          ===========================   =================
          linestyle                     description
          ===========================   =================
          ``'-'`` or ``'solid'``        solid line
          ``'--'`` or  ``'dashed'``     dashed line
          ``'-.'`` or  ``'dashdot'``    dash-dotted line
          ``':'`` or ``'dotted'``       dotted line
          ===========================   =================
  
          Alternatively a dash tuple of the following form can be provided::
  
              (offset, onoffseq),
  
          where ``onoffseq`` is an even length tuple of on and off ink in points.
  
          Parameters
          ----------
          ls : str or tuple or list thereof
              Valid values for individual linestyles include {'-', '--', '-.',
              ':', '', (offset, on-off-seq)}. See `.Line2D.set_linestyle` for a
              complete description.
          """
          try:
              if isinstance(ls, str):
                  ls = cbook.ls_mapper.get(ls, ls)
                  dashes = [mlines._get_dash_pattern(ls)]
              else:
                  try:
                      dashes = [mlines._get_dash_pattern(ls)]
                  except ValueError:
                      dashes = [mlines._get_dash_pattern(x) for x in ls]
  
          except ValueError as err:
              raise ValueError('Do not know how to convert {!r} to '
                               'dashes'.format(ls)) from err
  
          # get the list of raw 'unscaled' dash patterns
          self._us_linestyles = dashes
  
          # broadcast and scale the lw and dash patterns
          self._linewidths, self._linestyles = self._bcast_lwls(
              self._us_lw, self._us_linestyles)
  
      @docstring.interpd
      def set_capstyle(self, cs):
          """
          Set the `.CapStyle` for the collection (for all its elements).
  
          Parameters
          ----------
          cs : `.CapStyle` or %(CapStyle)s
          """
          self._capstyle = CapStyle(cs)
  
      def get_capstyle(self):
          return self._capstyle.name
  
      @docstring.interpd
      def set_joinstyle(self, js):
          """
          Set the `.JoinStyle` for the collection (for all its elements).
  
          Parameters
          ----------
          js : `.JoinStyle` or %(JoinStyle)s
          """
          self._joinstyle = JoinStyle(js)
  
      def get_joinstyle(self):
          return self._joinstyle.name
  
      @staticmethod
      def _bcast_lwls(linewidths, dashes):
          """
          Internal helper function to broadcast + scale ls/lw
  
          In the collection drawing code, the linewidth and linestyle are cycled
          through as circular buffers (via ``v[i % len(v)]``).  Thus, if we are
          going to scale the dash pattern at set time (not draw time) we need to
          do the broadcasting now and expand both lists to be the same length.
  
          Parameters
          ----------
          linewidths : list
              line widths of collection
          dashes : list
              dash specification (offset, (dash pattern tuple))
  
          Returns
          -------
          linewidths, dashes : list
              Will be the same length, dashes are scaled by paired linewidth
          """
          if mpl.rcParams['_internal.classic_mode']:
              return linewidths, dashes
          # make sure they are the same length so we can zip them
          if len(dashes) != len(linewidths):
              l_dashes = len(dashes)
              l_lw = len(linewidths)
              gcd = math.gcd(l_dashes, l_lw)
              dashes = list(dashes) * (l_lw // gcd)
              linewidths = list(linewidths) * (l_dashes // gcd)
  
          # scale the dash patters
          dashes = [mlines._scale_dashes(o, d, lw)
                    for (o, d), lw in zip(dashes, linewidths)]
  
          return linewidths, dashes
  
      def set_antialiased(self, aa):
          """
          Set the antialiasing state for rendering.
  
          Parameters
          ----------
          aa : bool or list of bools
          """
          if aa is None:
              aa = self._get_default_antialiased()
          self._antialiaseds = np.atleast_1d(np.asarray(aa, bool))
          self.stale = True
  
      def _get_default_antialiased(self):
          # This may be overridden in a subclass.
          return mpl.rcParams['patch.antialiased']
  
      def set_color(self, c):
          """
          Set both the edgecolor and the facecolor.
  
          Parameters
          ----------
          c : color or list of rgba tuples
  
          See Also
          --------
          Collection.set_facecolor, Collection.set_edgecolor
              For setting the edge or face color individually.
          """
          self.set_facecolor(c)
          self.set_edgecolor(c)
  
      def _get_default_facecolor(self):
          # This may be overridden in a subclass.
          return mpl.rcParams['patch.facecolor']
  
      def _set_facecolor(self, c):
          if c is None:
              c = self._get_default_facecolor()
  
          self._facecolors = mcolors.to_rgba_array(c, self._alpha)
          self.stale = True
  
      def set_facecolor(self, c):
          """
          Set the facecolor(s) of the collection. *c* can be a color (all patches
          have same color), or a sequence of colors; if it is a sequence the
          patches will cycle through the sequence.
  
          If *c* is 'none', the patch will not be filled.
  
          Parameters
          ----------
          c : color or list of colors
          """
          if isinstance(c, str) and c.lower() in ("none", "face"):
              c = c.lower()
          self._original_facecolor = c
          self._set_facecolor(c)
  
      def get_facecolor(self):
          return self._facecolors
  
      def get_edgecolor(self):
          if cbook._str_equal(self._edgecolors, 'face'):
              return self.get_facecolor()
          else:
              return self._edgecolors
  
      def _get_default_edgecolor(self):
          # This may be overridden in a subclass.
          return mpl.rcParams['patch.edgecolor']
  
      def _set_edgecolor(self, c):
          set_hatch_color = True
          if c is None:
              if (mpl.rcParams['patch.force_edgecolor']
                      or self._edge_default
                      or cbook._str_equal(self._original_facecolor, 'none')):
                  c = self._get_default_edgecolor()
              else:
                  c = 'none'
                  set_hatch_color = False
          if cbook._str_lower_equal(c, 'face'):
              self._edgecolors = 'face'
              self.stale = True
              return
          self._edgecolors = mcolors.to_rgba_array(c, self._alpha)
          if set_hatch_color and len(self._edgecolors):
              self._hatch_color = tuple(self._edgecolors[0])
          self.stale = True
  
      def set_edgecolor(self, c):
          """
          Set the edgecolor(s) of the collection.
  
          Parameters
          ----------
          c : color or list of colors or 'face'
              The collection edgecolor(s).  If a sequence, the patches cycle
              through it.  If 'face', match the facecolor.
          """
          # We pass through a default value for use in LineCollection.
          # This allows us to maintain None as the default indicator in
          # _original_edgecolor.
          if isinstance(c, str) and c.lower() in ("none", "face"):
              c = c.lower()
          self._original_edgecolor = c
          self._set_edgecolor(c)
  
      def set_alpha(self, alpha):
          """
          Set the transparency of the collection.
  
          Parameters
          ----------
          alpha : float or array of float or None
              If not None, *alpha* values must be between 0 and 1, inclusive.
              If an array is provided, its length must match the number of
              elements in the collection.  Masked values and nans are not
              supported.
          """
          artist.Artist._set_alpha_for_array(self, alpha)
          self._set_facecolor(self._original_facecolor)
          self._set_edgecolor(self._original_edgecolor)
  
      set_alpha.__doc__ = artist.Artist._set_alpha_for_array.__doc__
  
      def get_linewidth(self):
          return self._linewidths
  
      def get_linestyle(self):
          return self._linestyles
  
      def _set_mappable_flags(self):
          """
          Determine whether edges and/or faces are color-mapped.
  
          This is a helper for update_scalarmappable.
          It sets Boolean flags '_edge_is_mapped' and '_face_is_mapped'.
  
          Returns
          -------
          mapping_change : bool
              True if either flag is True, or if a flag has changed.
          """
          # The flags are initialized to None to ensure this returns True
          # the first time it is called.
          edge0 = self._edge_is_mapped
          face0 = self._face_is_mapped
          # After returning, the flags must be Booleans, not None.
          self._edge_is_mapped = False
          self._face_is_mapped = False
          if self._A is not None:
              if not cbook._str_equal(self._original_facecolor, 'none'):
                  self._face_is_mapped = True
                  if cbook._str_equal(self._original_edgecolor, 'face'):
                      self._edge_is_mapped = True
              else:
                  if self._original_edgecolor is None:
                      self._edge_is_mapped = True
  
          mapped = self._face_is_mapped or self._edge_is_mapped
          changed = (edge0 is None or face0 is None
                     or self._edge_is_mapped != edge0
                     or self._face_is_mapped != face0)
          return mapped or changed
  
      def update_scalarmappable(self):
          """
          Update colors from the scalar mappable array, if any.
  
          Assign colors to edges and faces based on the array and/or
          colors that were directly set, as appropriate.
          """
          if not self._set_mappable_flags():
              return
          # Allow possibility to call 'self.set_array(None)'.
          if self._A is not None:
              # QuadMesh can map 2d arrays (but pcolormesh supplies 1d array)
              if self._A.ndim > 1 and not isinstance(self, QuadMesh):
                  raise ValueError('Collections can only map rank 1 arrays')
              if np.iterable(self._alpha):
                  if self._alpha.size != self._A.size:
                      raise ValueError(
                          f'Data array shape, {self._A.shape} '
                          'is incompatible with alpha array shape, '
                          f'{self._alpha.shape}. '
                          'This can occur with the deprecated '
                          'behavior of the "flat" shading option, '
                          'in which a row and/or column of the data '
                          'array is dropped.')
                  # pcolormesh, scatter, maybe others flatten their _A
                  self._alpha = self._alpha.reshape(self._A.shape)
              self._mapped_colors = self.to_rgba(self._A, self._alpha)
  
          if self._face_is_mapped:
              self._facecolors = self._mapped_colors
          else:
              self._set_facecolor(self._original_facecolor)
          if self._edge_is_mapped:
              self._edgecolors = self._mapped_colors
          else:
              self._set_edgecolor(self._original_edgecolor)
          self.stale = True
  
      def get_fill(self):
          """Return whether face is colored."""
          return not cbook._str_lower_equal(self._original_facecolor, "none")
  
      def update_from(self, other):
          """Copy properties from other to self."""
  
          artist.Artist.update_from(self, other)
          self._antialiaseds = other._antialiaseds
          self._mapped_colors = other._mapped_colors
          self._edge_is_mapped = other._edge_is_mapped
          self._original_edgecolor = other._original_edgecolor
          self._edgecolors = other._edgecolors
          self._face_is_mapped = other._face_is_mapped
          self._original_facecolor = other._original_facecolor
          self._facecolors = other._facecolors
          self._linewidths = other._linewidths
          self._linestyles = other._linestyles
          self._us_linestyles = other._us_linestyles
          self._pickradius = other._pickradius
          self._hatch = other._hatch
  
          # update_from for scalarmappable
          self._A = other._A
          self.norm = other.norm
          self.cmap = other.cmap
          self.stale = True
  
  
  class _CollectionWithSizes(Collection):
      """
      Base class for collections that have an array of sizes.
      """
      _factor = 1.0
  
      def get_sizes(self):
          """
          Return the sizes ('areas') of the elements in the collection.
  
          Returns
          -------
          array
              The 'area' of each element.
          """
          return self._sizes
  
      def set_sizes(self, sizes, dpi=72.0):
          """
          Set the sizes of each member of the collection.
  
          Parameters
          ----------
          sizes : ndarray or None
              The size to set for each element of the collection.  The
              value is the 'area' of the element.
          dpi : float, default: 72
              The dpi of the canvas.
          """
          if sizes is None:
              self._sizes = np.array([])
              self._transforms = np.empty((0, 3, 3))
          else:
              self._sizes = np.asarray(sizes)
              self._transforms = np.zeros((len(self._sizes), 3, 3))
              scale = np.sqrt(self._sizes) * dpi / 72.0 * self._factor
              self._transforms[:, 0, 0] = scale
              self._transforms[:, 1, 1] = scale
              self._transforms[:, 2, 2] = 1.0
          self.stale = True
  
      @artist.allow_rasterization
      def draw(self, renderer):
          self.set_sizes(self._sizes, self.figure.dpi)
          super().draw(renderer)
  
  
  class PathCollection(_CollectionWithSizes):
      r"""
      A collection of `~.path.Path`\s, as created by e.g. `~.Axes.scatter`.
      """
  
      def __init__(self, paths, sizes=None, **kwargs):
          """
          Parameters
          ----------
          paths : list of `.path.Path`
              The paths that will make up the `.Collection`.
          sizes : array-like
              The factor by which to scale each drawn `~.path.Path`. One unit
              squared in the Path's data space is scaled to be ``sizes**2``
              points when rendered.
          **kwargs
              Forwarded to `.Collection`.
          """
  
          super().__init__(**kwargs)
          self.set_paths(paths)
          self.set_sizes(sizes)
          self.stale = True
  
      def set_paths(self, paths):
          self._paths = paths
          self.stale = True
  
      def get_paths(self):
          return self._paths
  
      def legend_elements(self, prop="colors", num="auto",
                          fmt=None, func=lambda x: x, **kwargs):
          """
          Create legend handles and labels for a PathCollection.
  
          Each legend handle is a `.Line2D` representing the Path that was drawn,
          and each label is a string what each Path represents.
  
          This is useful for obtaining a legend for a `~.Axes.scatter` plot;
          e.g.::
  
              scatter = plt.scatter([1, 2, 3],  [4, 5, 6],  c=[7, 2, 3])
              plt.legend(*scatter.legend_elements())
  
          creates three legend elements, one for each color with the numerical
          values passed to *c* as the labels.
  
          Also see the :ref:`automatedlegendcreation` example.
  
          Parameters
          ----------
          prop : {"colors", "sizes"}, default: "colors"
              If "colors", the legend handles will show the different colors of
              the collection. If "sizes", the legend will show the different
              sizes. To set both, use *kwargs* to directly edit the `.Line2D`
              properties.
          num : int, None, "auto" (default), array-like, or `~.ticker.Locator`
              Target number of elements to create.
              If None, use all unique elements of the mappable array. If an
              integer, target to use *num* elements in the normed range.
              If *"auto"*, try to determine which option better suits the nature
              of the data.
              The number of created elements may slightly deviate from *num* due
              to a `~.ticker.Locator` being used to find useful locations.
              If a list or array, use exactly those elements for the legend.
              Finally, a `~.ticker.Locator` can be provided.
          fmt : str, `~matplotlib.ticker.Formatter`, or None (default)
              The format or formatter to use for the labels. If a string must be
              a valid input for a `.StrMethodFormatter`. If None (the default),
              use a `.ScalarFormatter`.
          func : function, default: ``lambda x: x``
              Function to calculate the labels.  Often the size (or color)
              argument to `~.Axes.scatter` will have been pre-processed by the
              user using a function ``s = f(x)`` to make the markers visible;
              e.g. ``size = np.log10(x)``.  Providing the inverse of this
              function here allows that pre-processing to be inverted, so that
              the legend labels have the correct values; e.g. ``func = lambda
              x: 10**x``.
          **kwargs
              Allowed keyword arguments are *color* and *size*. E.g. it may be
              useful to set the color of the markers if *prop="sizes"* is used;
              similarly to set the size of the markers if *prop="colors"* is
              used. Any further parameters are passed onto the `.Line2D`
              instance. This may be useful to e.g. specify a different
              *markeredgecolor* or *alpha* for the legend handles.
  
          Returns
          -------
          handles : list of `.Line2D`
              Visual representation of each element of the legend.
          labels : list of str
              The string labels for elements of the legend.
          """
          handles = []
          labels = []
          hasarray = self.get_array() is not None
          if fmt is None:
              fmt = mpl.ticker.ScalarFormatter(useOffset=False, useMathText=True)
          elif isinstance(fmt, str):
              fmt = mpl.ticker.StrMethodFormatter(fmt)
          fmt.create_dummy_axis()
  
          if prop == "colors":
              if not hasarray:
                  warnings.warn("Collection without array used. Make sure to "
                                "specify the values to be colormapped via the "
                                "`c` argument.")
                  return handles, labels
              u = np.unique(self.get_array())
              size = kwargs.pop("size", mpl.rcParams["lines.markersize"])
          elif prop == "sizes":
              u = np.unique(self.get_sizes())
              color = kwargs.pop("color", "k")
          else:
              raise ValueError("Valid values for `prop` are 'colors' or "
                               f"'sizes'. You supplied '{prop}' instead.")
  
          fu = func(u)
          fmt.axis.set_view_interval(fu.min(), fu.max())
          fmt.axis.set_data_interval(fu.min(), fu.max())
          if num == "auto":
              num = 9
              if len(u) <= num:
                  num = None
          if num is None:
              values = u
              label_values = func(values)
          else:
              if prop == "colors":
                  arr = self.get_array()
              elif prop == "sizes":
                  arr = self.get_sizes()
              if isinstance(num, mpl.ticker.Locator):
                  loc = num
              elif np.iterable(num):
                  loc = mpl.ticker.FixedLocator(num)
              else:
                  num = int(num)
                  loc = mpl.ticker.MaxNLocator(nbins=num, min_n_ticks=num-1,
                                               steps=[1, 2, 2.5, 3, 5, 6, 8, 10])
              label_values = loc.tick_values(func(arr).min(), func(arr).max())
              cond = ((label_values >= func(arr).min()) &
                      (label_values <= func(arr).max()))
              label_values = label_values[cond]
              yarr = np.linspace(arr.min(), arr.max(), 256)
              xarr = func(yarr)
              ix = np.argsort(xarr)
              values = np.interp(label_values, xarr[ix], yarr[ix])
  
          kw = dict(markeredgewidth=self.get_linewidths()[0],
                    alpha=self.get_alpha())
          kw.update(kwargs)
  
          for val, lab in zip(values, label_values):
              if prop == "colors":
                  color = self.cmap(self.norm(val))
              elif prop == "sizes":
                  size = np.sqrt(val)
                  if np.isclose(size, 0.0):
                      continue
              h = mlines.Line2D([0], [0], ls="", color=color, ms=size,
                                marker=self.get_paths()[0], **kw)
              handles.append(h)
              if hasattr(fmt, "set_locs"):
                  fmt.set_locs(label_values)
              l = fmt(lab)
              labels.append(l)
  
          return handles, labels
  
  
  class PolyCollection(_CollectionWithSizes):
      def __init__(self, verts, sizes=None, closed=True, **kwargs):
          """
          Parameters
          ----------
          verts : list of array-like
              The sequence of polygons [*verts0*, *verts1*, ...] where each
              element *verts_i* defines the vertices of polygon *i* as a 2D
              array-like of shape (M, 2).
          sizes : array-like, default: None
              Squared scaling factors for the polygons. The coordinates of each
              polygon *verts_i* are multiplied by the square-root of the
              corresponding entry in *sizes* (i.e., *sizes* specify the scaling
              of areas). The scaling is applied before the Artist master
              transform.
          closed : bool, default: True
              Whether the polygon should be closed by adding a CLOSEPOLY
              connection at the end.
          **kwargs
              Forwarded to `.Collection`.
          """
          super().__init__(**kwargs)
          self.set_sizes(sizes)
          self.set_verts(verts, closed)
          self.stale = True
  
      def set_verts(self, verts, closed=True):
          """
          Set the vertices of the polygons.
  
          Parameters
          ----------
          verts : list of array-like
              The sequence of polygons [*verts0*, *verts1*, ...] where each
              element *verts_i* defines the vertices of polygon *i* as a 2D
              array-like of shape (M, 2).
          closed : bool, default: True
              Whether the polygon should be closed by adding a CLOSEPOLY
              connection at the end.
          """
          self.stale = True
          if isinstance(verts, np.ma.MaskedArray):
              verts = verts.astype(float).filled(np.nan)
  
          # No need to do anything fancy if the path isn't closed.
          if not closed:
              self._paths = [mpath.Path(xy) for xy in verts]
              return
  
          # Fast path for arrays
          if isinstance(verts, np.ndarray) and len(verts.shape) == 3:
              verts_pad = np.concatenate((verts, verts[:, :1]), axis=1)
              # Creating the codes once is much faster than having Path do it
              # separately each time by passing closed=True.
              codes = np.empty(verts_pad.shape[1], dtype=mpath.Path.code_type)
              codes[:] = mpath.Path.LINETO
              codes[0] = mpath.Path.MOVETO
              codes[-1] = mpath.Path.CLOSEPOLY
              self._paths = [mpath.Path(xy, codes) for xy in verts_pad]
              return
  
          self._paths = []
          for xy in verts:
              if len(xy):
                  if isinstance(xy, np.ma.MaskedArray):
                      xy = np.ma.concatenate([xy, xy[:1]])
                  else:
                      xy = np.concatenate([xy, xy[:1]])
                  self._paths.append(mpath.Path(xy, closed=True))
              else:
                  self._paths.append(mpath.Path(xy))
  
      set_paths = set_verts
  
      def set_verts_and_codes(self, verts, codes):
          """Initialize vertices with path codes."""
          if len(verts) != len(codes):
              raise ValueError("'codes' must be a 1D list or array "
                               "with the same length of 'verts'")
          self._paths = []
          for xy, cds in zip(verts, codes):
              if len(xy):
                  self._paths.append(mpath.Path(xy, cds))
              else:
                  self._paths.append(mpath.Path(xy))
          self.stale = True
  
  
  class BrokenBarHCollection(PolyCollection):
      """
      A collection of horizontal bars spanning *yrange* with a sequence of
      *xranges*.
      """
      def __init__(self, xranges, yrange, **kwargs):
          """
          Parameters
          ----------
          xranges : list of (float, float)
              The sequence of (left-edge-position, width) pairs for each bar.
          yrange : (float, float)
              The (lower-edge, height) common to all bars.
          **kwargs
              Forwarded to `.Collection`.
          """
          ymin, ywidth = yrange
          ymax = ymin + ywidth
          verts = [[(xmin, ymin),
                    (xmin, ymax),
                    (xmin + xwidth, ymax),
                    (xmin + xwidth, ymin),
                    (xmin, ymin)] for xmin, xwidth in xranges]
          super().__init__(verts, **kwargs)
  
      @classmethod
      def span_where(cls, x, ymin, ymax, where, **kwargs):
          """
          Return a `.BrokenBarHCollection` that plots horizontal bars from
          over the regions in *x* where *where* is True.  The bars range
          on the y-axis from *ymin* to *ymax*
  
          *kwargs* are passed on to the collection.
          """
          xranges = []
          for ind0, ind1 in cbook.contiguous_regions(where):
              xslice = x[ind0:ind1]
              if not len(xslice):
                  continue
              xranges.append((xslice[0], xslice[-1] - xslice[0]))
          return cls(xranges, [ymin, ymax - ymin], **kwargs)
  
  
  class RegularPolyCollection(_CollectionWithSizes):
      """A collection of n-sided regular polygons."""
  
      _path_generator = mpath.Path.unit_regular_polygon
      _factor = np.pi ** (-1/2)
  
      def __init__(self,
                   numsides,
                   rotation=0,
                   sizes=(1,),
                   **kwargs):
          """
          Parameters
          ----------
          numsides : int
              The number of sides of the polygon.
          rotation : float
              The rotation of the polygon in radians.
          sizes : tuple of float
              The area of the circle circumscribing the polygon in points^2.
          **kwargs
              Forwarded to `.Collection`.
  
          Examples
          --------
          See :doc:`/gallery/event_handling/lasso_demo` for a complete example::
  
              offsets = np.random.rand(20, 2)
              facecolors = [cm.jet(x) for x in np.random.rand(20)]
  
              collection = RegularPolyCollection(
                  numsides=5, # a pentagon
                  rotation=0, sizes=(50,),
                  facecolors=facecolors,
                  edgecolors=("black",),
                  linewidths=(1,),
                  offsets=offsets,
                  transOffset=ax.transData,
                  )
          """
          super().__init__(**kwargs)
          self.set_sizes(sizes)
          self._numsides = numsides
          self._paths = [self._path_generator(numsides)]
          self._rotation = rotation
          self.set_transform(transforms.IdentityTransform())
  
      def get_numsides(self):
          return self._numsides
  
      def get_rotation(self):
          return self._rotation
  
      @artist.allow_rasterization
      def draw(self, renderer):
          self.set_sizes(self._sizes, self.figure.dpi)
          self._transforms = [
              transforms.Affine2D(x).rotate(-self._rotation).get_matrix()
              for x in self._transforms
          ]
          # Explicitly not super().draw, because set_sizes must be called before
          # updating self._transforms.
          Collection.draw(self, renderer)
  
  
  class StarPolygonCollection(RegularPolyCollection):
      """Draw a collection of regular stars with *numsides* points."""
      _path_generator = mpath.Path.unit_regular_star
  
  
  class AsteriskPolygonCollection(RegularPolyCollection):
      """Draw a collection of regular asterisks with *numsides* points."""
      _path_generator = mpath.Path.unit_regular_asterisk
  
  
  class LineCollection(Collection):
      r"""
      Represents a sequence of `.Line2D`\s that should be drawn together.
  
      This class extends `.Collection` to represent a sequence of
      `.Line2D`\s instead of just a sequence of `.Patch`\s.
      Just as in `.Collection`, each property of a *LineCollection* may be either
      a single value or a list of values. This list is then used cyclically for
      each element of the LineCollection, so the property of the ``i``\th element
      of the collection is::
  
        prop[i % len(prop)]
  
      The properties of each member of a *LineCollection* default to their values
      in :rc:`lines.*` instead of :rc:`patch.*`, and the property *colors* is
      added in place of *edgecolors*.
      """
  
      _edge_default = True
  
      def __init__(self, segments,  # Can be None.
                   *args,           # Deprecated.
                   zorder=2,        # Collection.zorder is 1
                   **kwargs
                   ):
          """
          Parameters
          ----------
          segments : list of array-like
              A sequence of (*line0*, *line1*, *line2*), where::
  
                  linen = (x0, y0), (x1, y1), ... (xm, ym)
  
              or the equivalent numpy array with two columns. Each line
              can have a different number of segments.
          linewidths : float or list of float, default: :rc:`lines.linewidth`
              The width of each line in points.
          colors : color or list of color, default: :rc:`lines.color`
              A sequence of RGBA tuples (e.g., arbitrary color strings, etc, not
              allowed).
          antialiaseds : bool or list of bool, default: :rc:`lines.antialiased`
              Whether to use antialiasing for each line.
          zorder : int, default: 2
              zorder of the lines once drawn.
  
          facecolors : color or list of color, default: 'none'
              When setting *facecolors*, each line is interpreted as a boundary
              for an area, implicitly closing the path from the last point to the
              first point. The enclosed area is filled with *facecolor*.
              In order to manually specify what should count as the "interior" of
              each line, please use `.PathCollection` instead, where the
              "interior" can be specified by appropriate usage of
              `~.path.Path.CLOSEPOLY`.
  
          **kwargs
              Forwarded to `.Collection`.
          """
          argnames = ["linewidths", "colors", "antialiaseds", "linestyles",
                      "offsets", "transOffset", "norm", "cmap", "pickradius",
                      "zorder", "facecolors"]
          if args:
              argkw = {name: val for name, val in zip(argnames, args)}
              kwargs.update(argkw)
              cbook.warn_deprecated(
                  "3.4", message="Since %(since)s, passing LineCollection "
                  "arguments other than the first, 'segments', as positional "
                  "arguments is deprecated, and they will become keyword-only "
                  "arguments %(removal)s."
                  )
          # Unfortunately, mplot3d needs this explicit setting of 'facecolors'.
          kwargs.setdefault('facecolors', 'none')
          super().__init__(
              zorder=zorder,
              **kwargs)
          self.set_segments(segments)
  
      def set_segments(self, segments):
          if segments is None:
              return
          _segments = []
  
          for seg in segments:
              if not isinstance(seg, np.ma.MaskedArray):
                  seg = np.asarray(seg, float)
              _segments.append(seg)
  
          self._paths = [mpath.Path(_seg) for _seg in _segments]
          self.stale = True
  
      set_verts = set_segments  # for compatibility with PolyCollection
      set_paths = set_segments
  
      def get_segments(self):
          """
          Returns
          -------
          list
              List of segments in the LineCollection. Each list item contains an
              array of vertices.
          """
          segments = []
  
          for path in self._paths:
              vertices = [
                  vertex
                  for vertex, _
                  # Never simplify here, we want to get the data-space values
                  # back and there in no way to know the "right" simplification
                  # threshold so never try.
                  in path.iter_segments(simplify=False)
              ]
              vertices = np.asarray(vertices)
              segments.append(vertices)
  
          return segments
  
      def _get_default_linewidth(self):
          return mpl.rcParams['lines.linewidth']
  
      def _get_default_antialiased(self):
          return mpl.rcParams['lines.antialiased']
  
      def _get_default_edgecolor(self):
          return mpl.rcParams['lines.color']
  
      def _get_default_facecolor(self):
          return 'none'
  
      def set_color(self, c):
          """
          Set the edgecolor(s) of the LineCollection.
  
          Parameters
          ----------
          c : color or list of colors
              Single color (all lines have same color), or a
              sequence of rgba tuples; if it is a sequence the lines will
              cycle through the sequence.
          """
          self.set_edgecolor(c)
  
      set_colors = set_color
  
      def get_color(self):
          return self._edgecolors
  
      get_colors = get_color  # for compatibility with old versions
  
  
  class EventCollection(LineCollection):
      """
      A collection of locations along a single axis at which an "event" occurred.
  
      The events are given by a 1-dimensional array. They do not have an
      amplitude and are displayed as parallel lines.
      """
  
      _edge_default = True
  
      def __init__(self,
                   positions,  # Cannot be None.
                   orientation='horizontal',
                   lineoffset=0,
                   linelength=1,
                   linewidth=None,
                   color=None,
                   linestyle='solid',
                   antialiased=None,
                   **kwargs
                   ):
          """
          Parameters
          ----------
          positions : 1D array-like
              Each value is an event.
          orientation : {'horizontal', 'vertical'}, default: 'horizontal'
              The sequence of events is plotted along this direction.
              The marker lines of the single events are along the orthogonal
              direction.
          lineoffset : float, default: 0
              The offset of the center of the markers from the origin, in the
              direction orthogonal to *orientation*.
          linelength : float, default: 1
              The total height of the marker (i.e. the marker stretches from
              ``lineoffset - linelength/2`` to ``lineoffset + linelength/2``).
          linewidth : float or list thereof, default: :rc:`lines.linewidth`
              The line width of the event lines, in points.
          color : color or list of colors, default: :rc:`lines.color`
              The color of the event lines.
          linestyle : str or tuple or list thereof, default: 'solid'
              Valid strings are ['solid', 'dashed', 'dashdot', 'dotted',
              '-', '--', '-.', ':']. Dash tuples should be of the form::
  
                  (offset, onoffseq),
  
              where *onoffseq* is an even length tuple of on and off ink
              in points.
          antialiased : bool or list thereof, default: :rc:`lines.antialiased`
              Whether to use antialiasing for drawing the lines.
          **kwargs
              Forwarded to `.LineCollection`.
  
          Examples
          --------
          .. plot:: gallery/lines_bars_and_markers/eventcollection_demo.py
          """
          super().__init__([],
                           linewidths=linewidth, linestyles=linestyle,
                           colors=color, antialiaseds=antialiased,
                           **kwargs)
          self._is_horizontal = True  # Initial value, may be switched below.
          self._linelength = linelength
          self._lineoffset = lineoffset
          self.set_orientation(orientation)
          self.set_positions(positions)
  
      def get_positions(self):
          """
          Return an array containing the floating-point values of the positions.
          """
          pos = 0 if self.is_horizontal() else 1
          return [segment[0, pos] for segment in self.get_segments()]
  
      def set_positions(self, positions):
          """Set the positions of the events."""
          if positions is None:
              positions = []
          if np.ndim(positions) != 1:
              raise ValueError('positions must be one-dimensional')
          lineoffset = self.get_lineoffset()
          linelength = self.get_linelength()
          pos_idx = 0 if self.is_horizontal() else 1
          segments = np.empty((len(positions), 2, 2))
          segments[:, :, pos_idx] = np.sort(positions)[:, None]
          segments[:, 0, 1 - pos_idx] = lineoffset + linelength / 2
          segments[:, 1, 1 - pos_idx] = lineoffset - linelength / 2
          self.set_segments(segments)
  
      def add_positions(self, position):
          """Add one or more events at the specified positions."""
          if position is None or (hasattr(position, 'len') and
                                  len(position) == 0):
              return
          positions = self.get_positions()
          positions = np.hstack([positions, np.asanyarray(position)])
          self.set_positions(positions)
      extend_positions = append_positions = add_positions
  
      def is_horizontal(self):
          """True if the eventcollection is horizontal, False if vertical."""
          return self._is_horizontal
  
      def get_orientation(self):
          """
          Return the orientation of the event line ('horizontal' or 'vertical').
          """
          return 'horizontal' if self.is_horizontal() else 'vertical'
  
      def switch_orientation(self):
          """
          Switch the orientation of the event line, either from vertical to
          horizontal or vice versus.
          """
          segments = self.get_segments()
          for i, segment in enumerate(segments):
              segments[i] = np.fliplr(segment)
          self.set_segments(segments)
          self._is_horizontal = not self.is_horizontal()
          self.stale = True
  
      def set_orientation(self, orientation):
          """
          Set the orientation of the event line.
  
          Parameters
          ----------
          orientation : {'horizontal', 'vertical'}
          """
          is_horizontal = _api.check_getitem(
              {"horizontal": True, "vertical": False},
              orientation=orientation)
          if is_horizontal == self.is_horizontal():
              return
          self.switch_orientation()
  
      def get_linelength(self):
          """Return the length of the lines used to mark each event."""
          return self._linelength
  
      def set_linelength(self, linelength):
          """Set the length of the lines used to mark each event."""
          if linelength == self.get_linelength():
              return
          lineoffset = self.get_lineoffset()
          segments = self.get_segments()
          pos = 1 if self.is_horizontal() else 0
          for segment in segments:
              segment[0, pos] = lineoffset + linelength / 2.
              segment[1, pos] = lineoffset - linelength / 2.
          self.set_segments(segments)
          self._linelength = linelength
  
      def get_lineoffset(self):
          """Return the offset of the lines used to mark each event."""
          return self._lineoffset
  
      def set_lineoffset(self, lineoffset):
          """Set the offset of the lines used to mark each event."""
          if lineoffset == self.get_lineoffset():
              return
          linelength = self.get_linelength()
          segments = self.get_segments()
          pos = 1 if self.is_horizontal() else 0
          for segment in segments:
              segment[0, pos] = lineoffset + linelength / 2.
              segment[1, pos] = lineoffset - linelength / 2.
          self.set_segments(segments)
          self._lineoffset = lineoffset
  
      def get_linewidth(self):
          """Get the width of the lines used to mark each event."""
          return super().get_linewidth()[0]
  
      def get_linewidths(self):
          return super().get_linewidth()
  
      def get_color(self):
          """Return the color of the lines used to mark each event."""
          return self.get_colors()[0]
  
  
  class CircleCollection(_CollectionWithSizes):
      """A collection of circles, drawn using splines."""
  
      _factor = np.pi ** (-1/2)
  
      def __init__(self, sizes, **kwargs):
          """
          Parameters
          ----------
          sizes : float or array-like
              The area of each circle in points^2.
          **kwargs
              Forwarded to `.Collection`.
          """
          super().__init__(**kwargs)
          self.set_sizes(sizes)
          self.set_transform(transforms.IdentityTransform())
          self._paths = [mpath.Path.unit_circle()]
  
  
  class EllipseCollection(Collection):
      """A collection of ellipses, drawn using splines."""
  
      def __init__(self, widths, heights, angles, units='points', **kwargs):
          """
          Parameters
          ----------
          widths : array-like
              The lengths of the first axes (e.g., major axis lengths).
          heights : array-like
              The lengths of second axes.
          angles : array-like
              The angles of the first axes, degrees CCW from the x-axis.
          units : {'points', 'inches', 'dots', 'width', 'height', 'x', 'y', 'xy'}
              The units in which majors and minors are given; 'width' and
              'height' refer to the dimensions of the axes, while 'x' and 'y'
              refer to the *offsets* data units. 'xy' differs from all others in
              that the angle as plotted varies with the aspect ratio, and equals
              the specified angle only when the aspect ratio is unity.  Hence
              it behaves the same as the `~.patches.Ellipse` with
              ``axes.transData`` as its transform.
          **kwargs
              Forwarded to `Collection`.
          """
          super().__init__(**kwargs)
          self._widths = 0.5 * np.asarray(widths).ravel()
          self._heights = 0.5 * np.asarray(heights).ravel()
          self._angles = np.deg2rad(angles).ravel()
          self._units = units
          self.set_transform(transforms.IdentityTransform())
          self._transforms = np.empty((0, 3, 3))
          self._paths = [mpath.Path.unit_circle()]
  
      def _set_transforms(self):
          """Calculate transforms immediately before drawing."""
  
          ax = self.axes
          fig = self.figure
  
          if self._units == 'xy':
              sc = 1
          elif self._units == 'x':
              sc = ax.bbox.width / ax.viewLim.width
          elif self._units == 'y':
              sc = ax.bbox.height / ax.viewLim.height
          elif self._units == 'inches':
              sc = fig.dpi
          elif self._units == 'points':
              sc = fig.dpi / 72.0
          elif self._units == 'width':
              sc = ax.bbox.width
          elif self._units == 'height':
              sc = ax.bbox.height
          elif self._units == 'dots':
              sc = 1.0
          else:
              raise ValueError('unrecognized units: %s' % self._units)
  
          self._transforms = np.zeros((len(self._widths), 3, 3))
          widths = self._widths * sc
          heights = self._heights * sc
          sin_angle = np.sin(self._angles)
          cos_angle = np.cos(self._angles)
          self._transforms[:, 0, 0] = widths * cos_angle
          self._transforms[:, 0, 1] = heights * -sin_angle
          self._transforms[:, 1, 0] = widths * sin_angle
          self._transforms[:, 1, 1] = heights * cos_angle
          self._transforms[:, 2, 2] = 1.0
  
          _affine = transforms.Affine2D
          if self._units == 'xy':
              m = ax.transData.get_affine().get_matrix().copy()
              m[:2, 2:] = 0
              self.set_transform(_affine(m))
  
      @artist.allow_rasterization
      def draw(self, renderer):
          self._set_transforms()
          super().draw(renderer)
  
  
  class PatchCollection(Collection):
      """
      A generic collection of patches.
  
      This makes it easier to assign a colormap to a heterogeneous
      collection of patches.
  
      This also may improve plotting speed, since PatchCollection will
      draw faster than a large number of patches.
      """
  
      def __init__(self, patches, match_original=False, **kwargs):
          """
          *patches*
              a sequence of Patch objects.  This list may include
              a heterogeneous assortment of different patch types.
  
          *match_original*
              If True, use the colors and linewidths of the original
              patches.  If False, new colors may be assigned by
              providing the standard collection arguments, facecolor,
              edgecolor, linewidths, norm or cmap.
  
          If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds* are
          None, they default to their `.rcParams` patch setting, in sequence
          form.
  
          The use of `~matplotlib.cm.ScalarMappable` functionality is optional.
          If the `~matplotlib.cm.ScalarMappable` matrix ``_A`` has been set (via
          a call to `~.ScalarMappable.set_array`), at draw time a call to scalar
          mappable will be made to set the face colors.
          """
  
          if match_original:
              def determine_facecolor(patch):
                  if patch.get_fill():
                      return patch.get_facecolor()
                  return [0, 0, 0, 0]
  
              kwargs['facecolors'] = [determine_facecolor(p) for p in patches]
              kwargs['edgecolors'] = [p.get_edgecolor() for p in patches]
              kwargs['linewidths'] = [p.get_linewidth() for p in patches]
              kwargs['linestyles'] = [p.get_linestyle() for p in patches]
              kwargs['antialiaseds'] = [p.get_antialiased() for p in patches]
  
          super().__init__(**kwargs)
  
          self.set_paths(patches)
  
      def set_paths(self, patches):
          paths = [p.get_transform().transform_path(p.get_path())
                   for p in patches]
          self._paths = paths
  
  
  class TriMesh(Collection):
      """
      Class for the efficient drawing of a triangular mesh using Gouraud shading.
  
      A triangular mesh is a `~matplotlib.tri.Triangulation` object.
      """
      def __init__(self, triangulation, **kwargs):
          super().__init__(**kwargs)
          self._triangulation = triangulation
          self._shading = 'gouraud'
  
          self._bbox = transforms.Bbox.unit()
  
          # Unfortunately this requires a copy, unless Triangulation
          # was rewritten.
          xy = np.hstack((triangulation.x.reshape(-1, 1),
                          triangulation.y.reshape(-1, 1)))
          self._bbox.update_from_data_xy(xy)
  
      def get_paths(self):
          if self._paths is None:
              self.set_paths()
          return self._paths
  
      def set_paths(self):
          self._paths = self.convert_mesh_to_paths(self._triangulation)
  
      @staticmethod
      def convert_mesh_to_paths(tri):
          """
          Convert a given mesh into a sequence of `.Path` objects.
  
          This function is primarily of use to implementers of backends that do
          not directly support meshes.
          """
          triangles = tri.get_masked_triangles()
          verts = np.stack((tri.x[triangles], tri.y[triangles]), axis=-1)
          return [mpath.Path(x) for x in verts]
  
      @artist.allow_rasterization
      def draw(self, renderer):
          if not self.get_visible():
              return
          renderer.open_group(self.__class__.__name__, gid=self.get_gid())
          transform = self.get_transform()
  
          # Get a list of triangles and the color at each vertex.
          tri = self._triangulation
          triangles = tri.get_masked_triangles()
  
          verts = np.stack((tri.x[triangles], tri.y[triangles]), axis=-1)
  
          self.update_scalarmappable()
          colors = self._facecolors[triangles]
  
          gc = renderer.new_gc()
          self._set_gc_clip(gc)
          gc.set_linewidth(self.get_linewidth()[0])
          renderer.draw_gouraud_triangles(gc, verts, colors, transform.frozen())
          gc.restore()
          renderer.close_group(self.__class__.__name__)
  
  
  class QuadMesh(Collection):
      r"""
      Class for the efficient drawing of a quadrilateral mesh.
  
      A quadrilateral mesh is a grid of M by N adjacent qudrilaterals that are
      defined via a (M+1, N+1) grid of vertices. The quadrilateral (m, n) is
      defined by the vertices ::
  
                 (m+1, n) ----------- (m+1, n+1)
                    /                   /
                   /                 /
                  /               /
              (m, n) -------- (m, n+1)
  
      The mesh need not be regular and the polygons need not be convex.
  
      Parameters
      ----------
      coordinates : (M+1, N+1, 2) array-like
          The vertices. ``coordinates[m, n]`` specifies the (x, y) coordinates
          of vertex (m, n).
  
      antialiased : bool, default: True
  
      shading : {'flat', 'gouraud'}, default: 'flat'
  
      Notes
      -----
      Unlike other `.Collection`\s, the default *pickradius* of `.QuadMesh` is 0,
      i.e. `~.Artist.contains` checks whether the test point is within any of the
      mesh quadrilaterals.
  
      There exists a deprecated API version ``QuadMesh(M, N, coords)``, where
      the dimensions are given explicitly and ``coords`` is a (M*N, 2)
      array-like. This has been deprecated in Matplotlib 3.5. The following
      describes the semantics of this deprecated API.
  
      A quadrilateral mesh consists of a grid of vertices.
      The dimensions of this array are (*meshWidth* + 1, *meshHeight* + 1).
      Each vertex in the mesh has a different set of "mesh coordinates"
      representing its position in the topology of the mesh.
      For any values (*m*, *n*) such that 0 <= *m* <= *meshWidth*
      and 0 <= *n* <= *meshHeight*, the vertices at mesh coordinates
      (*m*, *n*), (*m*, *n* + 1), (*m* + 1, *n* + 1), and (*m* + 1, *n*)
      form one of the quadrilaterals in the mesh. There are thus
      (*meshWidth* * *meshHeight*) quadrilaterals in the mesh.  The mesh
      need not be regular and the polygons need not be convex.
  
      A quadrilateral mesh is represented by a (2 x ((*meshWidth* + 1) *
      (*meshHeight* + 1))) numpy array *coordinates*, where each row is
      the *x* and *y* coordinates of one of the vertices.  To define the
      function that maps from a data point to its corresponding color,
      use the :meth:`set_cmap` method.  Each of these arrays is indexed in
      row-major order by the mesh coordinates of the vertex (or the mesh
      coordinates of the lower left vertex, in the case of the colors).
  
      For example, the first entry in *coordinates* is the coordinates of the
      vertex at mesh coordinates (0, 0), then the one at (0, 1), then at (0, 2)
      .. (0, meshWidth), (1, 0), (1, 1), and so on.
      """
  
      def __init__(self, *args, **kwargs):
          # signature deprecation since="3.5": Change to new signature after the
          # deprecation has expired. Also remove setting __init__.__signature__,
          # and remove the Notes from the docstring.
          params = _api.select_matching_signature(
              [
                  lambda meshWidth, meshHeight, coordinates, antialiased=True,
                         shading='flat', **kwargs: locals(),
                  lambda coordinates, antialiased=True, shading='flat', **kwargs:
                         locals()
              ],
              *args, **kwargs).values()
          *old_w_h, coords, antialiased, shading, kwargs = params
          if old_w_h:  # The old signature matched.
              _api.warn_deprecated(
                  "3.5",
                  message="This usage of Quadmesh is deprecated: Parameters "
                          "meshWidth and meshHeights will be removed; "
                          "coordinates must be 2D; all parameters except "
                          "coordinates will be keyword-only.")
              w, h = old_w_h
              coords = np.asarray(coords, np.float64).reshape((h + 1, w + 1, 2))
          kwargs.setdefault("pickradius", 0)
          # end of signature deprecation code
  
          _api.check_shape((None, None, 2), coordinates=coords)
          self._coordinates = coords
          self._antialiased = antialiased
          self._shading = shading
          self._bbox = transforms.Bbox.unit()
          self._bbox.update_from_data_xy(self._coordinates.reshape(-1, 2))
          # super init delayed after own init because array kwarg requires
          # self._coordinates and self._shading
          super().__init__(**kwargs)
  
      # Only needed during signature deprecation
      __init__.__signature__ = inspect.signature(
          lambda self, coordinates, *,
                 antialiased=True, shading='flat', pickradius=0, **kwargs: None)
  
      def get_paths(self):
          if self._paths is None:
              self.set_paths()
          return self._paths
  
      def set_paths(self):
          self._paths = self._convert_mesh_to_paths(self._coordinates)
          self.stale = True
  
      def set_array(self, A):
          """
          Set the data values.
  
          Parameters
          ----------
          A : (M, N) array-like or M*N array-like
              If the values are provided as a 2D grid, the shape must match the
              coordinates grid. If the values are 1D, they are reshaped to 2D.
              M, N follow from the coordinates grid, where the coordinates grid
              shape is (M, N) for 'gouraud' *shading* and (M+1, N+1) for 'flat'
              shading.
          """
          height, width = self._coordinates.shape[0:-1]
          misshapen_data = False
          faulty_data = False
  
          if self._shading == 'flat':
              h, w = height-1, width-1
          else:
              h, w = height, width
  
          if A is not None:
              shape = np.shape(A)
              if len(shape) == 1:
                  if shape[0] != (h*w):
                      faulty_data = True
              elif shape != (h, w):
                  if np.prod(shape) == (h * w):
                      misshapen_data = True
                  else:
                      faulty_data = True
  
              if misshapen_data:
                  _api.warn_deprecated(
                      "3.5", message=f"For X ({width}) and Y ({height}) "
                      f"with {self._shading} shading, the expected shape of "
                      f"A is ({h}, {w}). Passing A ({A.shape}) is deprecated "
                      "since %(since)s and will become an error %(removal)s.")
  
              if faulty_data:
                  raise TypeError(
                      f"Dimensions of A {A.shape} are incompatible with "
                      f"X ({width}) and/or Y ({height})")
  
          return super().set_array(A)
  
      def get_datalim(self, transData):
          return (self.get_transform() - transData).transform_bbox(self._bbox)
  
      def get_coordinates(self):
          """
          Return the vertices of the mesh as an (M+1, N+1, 2) array.
  
          M, N are the number of quadrilaterals in the rows / columns of the
          mesh, corresponding to (M+1, N+1) vertices.
          The last dimension specifies the components (x, y).
          """
          return self._coordinates
  
      @staticmethod
      @_api.deprecated("3.5", alternative="QuadMesh(coordinates).get_paths()")
      def convert_mesh_to_paths(meshWidth, meshHeight, coordinates):
          return QuadMesh._convert_mesh_to_paths(coordinates)
  
      @staticmethod
      def _convert_mesh_to_paths(coordinates):
          """
          Convert a given mesh into a sequence of `.Path` objects.
  
          This function is primarily of use to implementers of backends that do
          not directly support quadmeshes.
          """
          if isinstance(coordinates, np.ma.MaskedArray):
              c = coordinates.data
          else:
              c = coordinates
          points = np.concatenate([
              c[:-1, :-1],
              c[:-1, 1:],
              c[1:, 1:],
              c[1:, :-1],
              c[:-1, :-1]
          ], axis=2).reshape((-1, 5, 2))
          return [mpath.Path(x) for x in points]
  
      @_api.deprecated("3.5")
      def convert_mesh_to_triangles(self, meshWidth, meshHeight, coordinates):
          return self._convert_mesh_to_triangles(coordinates)
  
      def _convert_mesh_to_triangles(self, coordinates):
          """
          Convert a given mesh into a sequence of triangles, each point
          with its own color.  The result can be used to construct a call to
          `~.RendererBase.draw_gouraud_triangle`.
          """
          if isinstance(coordinates, np.ma.MaskedArray):
              p = coordinates.data
          else:
              p = coordinates
  
          p_a = p[:-1, :-1]
          p_b = p[:-1, 1:]
          p_c = p[1:, 1:]
          p_d = p[1:, :-1]
          p_center = (p_a + p_b + p_c + p_d) / 4.0
          triangles = np.concatenate([
              p_a, p_b, p_center,
              p_b, p_c, p_center,
              p_c, p_d, p_center,
              p_d, p_a, p_center,
          ], axis=2).reshape((-1, 3, 2))
  
          c = self.get_facecolor().reshape((*coordinates.shape[:2], 4))
          c_a = c[:-1, :-1]
          c_b = c[:-1, 1:]
          c_c = c[1:, 1:]
          c_d = c[1:, :-1]
          c_center = (c_a + c_b + c_c + c_d) / 4.0
          colors = np.concatenate([
              c_a, c_b, c_center,
              c_b, c_c, c_center,
              c_c, c_d, c_center,
              c_d, c_a, c_center,
          ], axis=2).reshape((-1, 3, 4))
  
          return triangles, colors
  
      @artist.allow_rasterization
      def draw(self, renderer):
          if not self.get_visible():
              return
          renderer.open_group(self.__class__.__name__, self.get_gid())
          transform = self.get_transform()
          transOffset = self.get_offset_transform()
          offsets = self._offsets
  
          if self.have_units():
              if len(self._offsets):
                  xs = self.convert_xunits(self._offsets[:, 0])
                  ys = self.convert_yunits(self._offsets[:, 1])
                  offsets = np.column_stack([xs, ys])
  
          self.update_scalarmappable()
  
          if not transform.is_affine:
              coordinates = self._coordinates.reshape((-1, 2))
              coordinates = transform.transform(coordinates)
              coordinates = coordinates.reshape(self._coordinates.shape)
              transform = transforms.IdentityTransform()
          else:
              coordinates = self._coordinates
  
          if not transOffset.is_affine:
              offsets = transOffset.transform_non_affine(offsets)
              transOffset = transOffset.get_affine()
  
          gc = renderer.new_gc()
          gc.set_snap(self.get_snap())
          self._set_gc_clip(gc)
          gc.set_linewidth(self.get_linewidth()[0])
  
          if self._shading == 'gouraud':
              triangles, colors = self._convert_mesh_to_triangles(coordinates)
              renderer.draw_gouraud_triangles(
                  gc, triangles, colors, transform.frozen())
          else:
              renderer.draw_quad_mesh(
                  gc, transform.frozen(),
                  coordinates.shape[1] - 1, coordinates.shape[0] - 1,
                  coordinates, offsets, transOffset,
                  # Backends expect flattened rgba arrays (n*m, 4) for fc and ec
                  self.get_facecolor().reshape((-1, 4)),
                  self._antialiased, self.get_edgecolors().reshape((-1, 4)))
          gc.restore()
          renderer.close_group(self.__class__.__name__)
          self.stale = False
  
      def get_cursor_data(self, event):
          contained, info = self.contains(event)
          if len(info["ind"]) == 1:
              ind, = info["ind"]
              return self.get_array()[ind]
          else:
              return None
  