1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065 |
- """
- 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 math
- from numbers import Number
- import numpy as np
- import matplotlib as mpl
- from . import (_path, artist, cbook, cm, colors as mcolors, docstring,
- lines as mlines, path as mpath, transforms)
- import warnings
- @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))
- _transOffset = transforms.IdentityTransform()
- #: 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
- @cbook._delete_parameter("3.3", "offset_position")
- 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,
- offset_position='screen',
- 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 : str, default: :rc:`patch.capstyle`
- Style to use for capping lines for all paths in the collection.
- See :doc:`/gallery/lines_bars_and_markers/joinstyle` for
- a demonstration of each of the allowed values.
- joinstyle : str, default: :rc:`patch.joinstyle`
- Style to use for joining lines for all paths in the collection.
- See :doc:`/gallery/lines_bars_and_markers/joinstyle` for
- a demonstration of each of the allowed values.
- antialiaseds : bool or list of bool, default: :rc:`patch.antialiased`
- Whether each pach 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.
- offset_position : {'screen' (default), 'data' (deprecated)}
- If set to 'data' (deprecated), *offsets* will be treated as if it
- is in data coordinates instead of in screen coordinates.
- 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_demo` 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]
- self._is_filled = True # May be modified by set_facecolor().
- 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"
- if offset_position != "screen":
- self.set_offset_position(offset_position) # emit deprecation.
- self.set_zorder(zorder)
- if capstyle:
- self.set_capstyle(capstyle)
- else:
- self._capstyle = None
- if joinstyle:
- self.set_joinstyle(joinstyle)
- else:
- self._joinstyle = None
- self._offsets = np.zeros((1, 2))
- # save if offsets passed in were none...
- self._offsetsNone = offsets is None
- self._uniform_offsets = None
- if offsets is not None:
- offsets = np.asanyarray(offsets, float)
- # Broadcast (2,) -> (1, 2) but nothing else.
- if offsets.shape == (2,):
- offsets = offsets[None, :]
- if transOffset is not None:
- self._offsets = offsets
- self._transOffset = transOffset
- else:
- self._uniform_offsets = offsets
- 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):
- t = self._transOffset
- if (not isinstance(t, transforms.Transform)
- and hasattr(t, '_as_mpl_transform')):
- t = t._as_mpl_transform(self.axes)
- return t
- 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()
- if (not self._offsetsNone 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).
- result = mpath.get_path_collection_extents(
- transform.get_affine(), paths, self.get_transforms(),
- transOffset.transform_non_affine(offsets),
- transOffset.get_affine().frozen())
- return result.transformed(transData.inverted())
- if not self._offsetsNone:
- # 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():
- points = np.row_stack((offsets.min(axis=0),
- offsets.max(axis=0)))
- return transforms.Bbox(points)
- 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
- ----------
- d : 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', '.', '*'}
- """
- 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 : array-like (N, 2) or (2,)
- """
- offsets = np.asanyarray(offsets, float)
- if offsets.shape == (2,): # Broadcast (2,) -> (1, 2) but nothing else.
- offsets = offsets[None, :]
- # This decision is based on how they are initialized above in __init__.
- if self._uniform_offsets is None:
- self._offsets = offsets
- else:
- self._uniform_offsets = offsets
- self.stale = True
- def get_offsets(self):
- """Return the offsets for the collection."""
- # This decision is based on how they are initialized above in __init__.
- if self._uniform_offsets is None:
- return self._offsets
- else:
- return self._uniform_offsets
- @cbook.deprecated("3.3")
- def set_offset_position(self, offset_position):
- """
- Set how offsets are applied. If *offset_position* is 'screen'
- (default) the offset is applied after the master transform has
- been applied, that is, the offsets are in screen coordinates.
- If offset_position is 'data', the offset is applied before the
- master transform, i.e., the offsets are in data coordinates.
- Parameters
- ----------
- offset_position : {'screen', 'data'}
- """
- cbook._check_in_list(['screen', 'data'],
- offset_position=offset_position)
- self._offset_position = offset_position
- self.stale = True
- @cbook.deprecated("3.3")
- def get_offset_position(self):
- """
- Return how offsets are applied for the collection. If
- *offset_position* is 'screen', the offset is applied after the
- master transform has been applied, that is, the offsets are in
- screen coordinates. If offset_position is 'data', the offset
- is applied before the master transform, i.e., the offsets are
- in data coordinates.
- """
- return self._offset_position
- 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 = mpl.rcParams['patch.linewidth']
- if lw is None:
- lw = mpl.rcParams['lines.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)
- def set_capstyle(self, cs):
- """
- Set the capstyle for the collection (for all its elements).
- Parameters
- ----------
- cs : {'butt', 'round', 'projecting'}
- The capstyle.
- """
- mpl.rcsetup.validate_capstyle(cs)
- self._capstyle = cs
- def get_capstyle(self):
- return self._capstyle
- def set_joinstyle(self, js):
- """
- Set the joinstyle for the collection (for all its elements).
- Parameters
- ----------
- js : {'miter', 'round', 'bevel'}
- The joinstyle.
- """
- mpl.rcsetup.validate_joinstyle(js)
- self._joinstyle = js
- def get_joinstyle(self):
- return self._joinstyle
- @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 = mpl.rcParams['patch.antialiased']
- self._antialiaseds = np.atleast_1d(np.asarray(aa, bool))
- self.stale = True
- 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 _set_facecolor(self, c):
- if c is None:
- c = mpl.rcParams['patch.facecolor']
- self._is_filled = True
- try:
- if c.lower() == 'none':
- self._is_filled = False
- except AttributeError:
- pass
- 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
- """
- 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 _set_edgecolor(self, c):
- set_hatch_color = True
- if c is None:
- if (mpl.rcParams['patch.force_edgecolor'] or
- not self._is_filled or self._edge_default):
- c = mpl.rcParams['patch.edgecolor']
- else:
- c = 'none'
- set_hatch_color = False
- self._is_stroked = True
- try:
- if c.lower() == 'none':
- self._is_stroked = False
- except AttributeError:
- pass
- try:
- if c.lower() == 'face': # Special case: lookup in "get" method.
- self._edgecolors = 'face'
- return
- except AttributeError:
- pass
- 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.
- """
- self._original_edgecolor = c
- self._set_edgecolor(c)
- def set_alpha(self, alpha):
- # docstring inherited
- super().set_alpha(alpha)
- self._update_dict['array'] = True
- self._set_facecolor(self._original_facecolor)
- self._set_edgecolor(self._original_edgecolor)
- def get_linewidth(self):
- return self._linewidths
- def get_linestyle(self):
- return self._linestyles
- def update_scalarmappable(self):
- """Update colors from the scalar mappable array, if it is not None."""
- if self._A is None:
- return
- # QuadMesh can map 2d arrays
- if self._A.ndim > 1 and not isinstance(self, QuadMesh):
- raise ValueError('Collections can only map rank 1 arrays')
- if not self._check_update("array"):
- return
- if self._is_filled:
- self._facecolors = self.to_rgba(self._A, self._alpha)
- elif self._is_stroked:
- self._edgecolors = self.to_rgba(self._A, self._alpha)
- self.stale = True
- def get_fill(self):
- """Return whether fill is set."""
- return self._is_filled
- def update_from(self, other):
- """Copy properties from other to self."""
- artist.Artist.update_from(self, other)
- self._antialiaseds = other._antialiaseds
- self._original_edgecolor = other._original_edgecolor
- self._edgecolors = other._edgecolors
- 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
- # do we need to copy self._update_dict? -JJL
- 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)
- Collection.draw(self, 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.")
- fmt.set_bounds(func(u).min(), func(u).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]
- xarr = np.linspace(arr.min(), arr.max(), 256)
- values = np.interp(label_values, func(xarr), xarr)
- 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`.
- """
- Collection.__init__(self, **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]
- PolyCollection.__init__(self, 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,
- )
- """
- Collection.__init__(self, **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
- ]
- 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.
- linewidths=None,
- colors=None,
- antialiaseds=None,
- linestyles='solid',
- offsets=None,
- transOffset=None,
- norm=None,
- cmap=None,
- pickradius=5,
- zorder=2,
- facecolors='none',
- **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'
- The facecolors of the LineCollection.
- Setting to a value other than 'none' will lead to each line being
- "filled in" as if there was an implicit line segment joining the
- last and first points of that line back around to each other. 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
- Forwareded to `.Collection`.
- """
- if colors is None:
- colors = mpl.rcParams['lines.color']
- if linewidths is None:
- linewidths = (mpl.rcParams['lines.linewidth'],)
- if antialiaseds is None:
- antialiaseds = (mpl.rcParams['lines.antialiased'],)
- colors = mcolors.to_rgba_array(colors)
- Collection.__init__(
- self,
- edgecolors=colors,
- facecolors=facecolors,
- linewidths=linewidths,
- linestyles=linestyles,
- antialiaseds=antialiaseds,
- offsets=offsets,
- transOffset=transOffset,
- norm=norm,
- cmap=cmap,
- 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)
- if self._uniform_offsets is not None:
- _segments = self._add_offsets(_segments)
- 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, _ in path.iter_segments()]
- vertices = np.asarray(vertices)
- segments.append(vertices)
- return segments
- def _add_offsets(self, segs):
- offsets = self._uniform_offsets
- Nsegs = len(segs)
- Noffs = offsets.shape[0]
- if Noffs == 1:
- for i in range(Nsegs):
- segs[i] = segs[i] + i * offsets
- else:
- for i in range(Nsegs):
- io = i % Noffs
- segs[i] = segs[i] + offsets[io:io + 1]
- return segs
- def set_color(self, c):
- """
- Set the color(s) of the LineCollection.
- Parameters
- ----------
- c : color or list of colors
- Single color (all patches have same color), or a
- sequence of rgba tuples; if it is a sequence the patches will
- cycle through the sequence.
- """
- self.set_edgecolor(c)
- self.stale = True
- 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" occured.
- 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
- """
- LineCollection.__init__(self,
- [],
- linewidths=linewidth,
- colors=color,
- antialiaseds=antialiased,
- linestyles=linestyle,
- **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=None):
- """
- Set the orientation of the event line.
- Parameters
- ----------
- orientation : {'horizontal', 'vertical'}
- """
- try:
- is_horizontal = cbook._check_getitem(
- {"horizontal": True, "vertical": False},
- orientation=orientation)
- except ValueError:
- if (orientation is None or orientation.lower() == "none"
- or orientation.lower() == "horizontal"):
- is_horizontal = True
- elif orientation.lower() == "vertical":
- is_horizontal = False
- else:
- raise
- normalized = "horizontal" if is_horizontal else "vertical"
- cbook.warn_deprecated(
- "3.3", message="Support for setting the orientation of "
- f"EventCollection to {orientation!r} is deprecated since "
- f"%(since)s and will be removed %(removal)s; please set it to "
- f"{normalized!r} instead.")
- 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(EventCollection, self).get_linewidth()[0]
- def get_linewidths(self):
- return super(EventCollection, self).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`.
- """
- Collection.__init__(self, **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`.
- """
- Collection.__init__(self, **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()
- Collection.draw(self, renderer)
- class PatchCollection(Collection):
- """
- A generic collection of patches.
- This makes it easier to assign a color map 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]
- Collection.__init__(self, **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):
- Collection.__init__(self, **kwargs)
- self._triangulation = triangulation
- self._shading = 'gouraud'
- self._is_filled = True
- 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):
- """
- Class for the efficient drawing of a quadrilateral mesh.
- 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.
- *shading* may be 'flat', or 'gouraud'
- """
- def __init__(self, meshWidth, meshHeight, coordinates,
- antialiased=True, shading='flat', **kwargs):
- Collection.__init__(self, **kwargs)
- self._meshWidth = meshWidth
- self._meshHeight = meshHeight
- # By converting to floats now, we can avoid that on every draw.
- self._coordinates = np.asarray(coordinates, float).reshape(
- (meshHeight + 1, meshWidth + 1, 2))
- self._antialiased = antialiased
- self._shading = shading
- self._bbox = transforms.Bbox.unit()
- self._bbox.update_from_data_xy(coordinates.reshape(
- ((meshWidth + 1) * (meshHeight + 1), 2)))
- 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._meshWidth, self._meshHeight, self._coordinates)
- self.stale = True
- def get_datalim(self, transData):
- return (self.get_transform() - transData).transform_bbox(self._bbox)
- @staticmethod
- def convert_mesh_to_paths(meshWidth, meshHeight, 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)
- points = points.reshape((meshWidth * meshHeight, 5, 2))
- return [mpath.Path(x) for x in points]
- def convert_mesh_to_triangles(self, meshWidth, meshHeight, coordinates):
- """
- Convert a given mesh into a sequence of triangles, each point
- with its own color. This is useful for experiments using
- `~.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)
- triangles = triangles.reshape((meshWidth * meshHeight * 4, 3, 2))
- c = self.get_facecolor().reshape((meshHeight + 1, meshWidth + 1, 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)
- colors = colors.reshape((meshWidth * meshHeight * 4, 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()
- self._set_gc_clip(gc)
- gc.set_linewidth(self.get_linewidth()[0])
- if self._shading == 'gouraud':
- triangles, colors = self.convert_mesh_to_triangles(
- self._meshWidth, self._meshHeight, coordinates)
- renderer.draw_gouraud_triangles(
- gc, triangles, colors, transform.frozen())
- else:
- renderer.draw_quad_mesh(
- gc, transform.frozen(), self._meshWidth, self._meshHeight,
- 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
- patchstr = artist.kwdoc(Collection)
- for k in ('QuadMesh', 'TriMesh', 'PolyCollection', 'BrokenBarHCollection',
- 'RegularPolyCollection', 'PathCollection',
- 'StarPolygonCollection', 'PatchCollection',
- 'CircleCollection', 'Collection',):
- docstring.interpd.update({k: patchstr})
- docstring.interpd.update(LineCollection=artist.kwdoc(LineCollection))
|