
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "users/explain/artists/patheffects_guide.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. meta::
        :keywords: codex

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_users_explain_artists_patheffects_guide.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_users_explain_artists_patheffects_guide.py:


.. redirect-from:: /tutorials/advance/patheffects_guide

.. _patheffects_guide:

==================
Path effects guide
==================

Defining paths that objects follow on a canvas.

.. py:currentmodule:: matplotlib.patheffects

Matplotlib's :mod:`.patheffects` module provides functionality to apply a
multiple draw stage to any Artist which can be rendered via a `.path.Path`.

Artists which can have a path effect applied to them include `.patches.Patch`,
`.lines.Line2D`, `.collections.Collection` and even `.text.Text`. Each artist's
path effects can be controlled via the `.Artist.set_path_effects` method,
which takes an iterable of `AbstractPathEffect` instances.

The simplest path effect is the `Normal` effect, which simply draws the artist
without any effect:

.. GENERATED FROM PYTHON SOURCE LINES 25-37

.. code-block:: Python


    import matplotlib.pyplot as plt

    import matplotlib.patheffects as path_effects

    fig = plt.figure(figsize=(5, 1.5))
    text = fig.text(0.5, 0.5, 'Hello path effects world!\nThis is the normal '
                              'path effect.\nPretty dull, huh?',
                    ha='center', va='center', size=20)
    text.set_path_effects([path_effects.Normal()])
    plt.show()




.. image-sg:: /users/explain/artists/images/sphx_glr_patheffects_guide_001.png
   :alt: patheffects guide
   :srcset: /users/explain/artists/images/sphx_glr_patheffects_guide_001.png, /users/explain/artists/images/sphx_glr_patheffects_guide_001_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 38-50

Whilst the plot doesn't look any different to what you would expect without
any path effects, the drawing of the text has now been changed to use the
path effects framework, opening up the possibilities for more interesting
examples.

Adding a shadow
---------------

A far more interesting path effect than `Normal` is the drop-shadow, which we
can apply to any of our path based artists. The classes `SimplePatchShadow`
and `SimpleLineShadow` do precisely this by drawing either a filled patch or
a line patch below the original artist:

.. GENERATED FROM PYTHON SOURCE LINES 50-61

.. code-block:: Python


    import matplotlib.patheffects as path_effects

    text = plt.text(0.5, 0.5, 'Hello path effects world!',
                    path_effects=[path_effects.withSimplePatchShadow()])

    plt.plot([0, 3, 2, 5], linewidth=5, color='blue',
             path_effects=[path_effects.SimpleLineShadow(),
                           path_effects.Normal()])
    plt.show()




.. image-sg:: /users/explain/artists/images/sphx_glr_patheffects_guide_002.png
   :alt: patheffects guide
   :srcset: /users/explain/artists/images/sphx_glr_patheffects_guide_002.png, /users/explain/artists/images/sphx_glr_patheffects_guide_002_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 62-73

Notice the two approaches to setting the path effects in this example. The
first uses the ``with*`` classes to include the desired functionality
automatically followed with the "normal" effect, whereas the latter
explicitly defines the two path effects to draw.

Making an Artist stand out
--------------------------

One nice way of making artists visually stand out is to draw an outline in
a bold color below the actual artist. The :class:`Stroke` path effect makes
this a relatively simple task:

.. GENERATED FROM PYTHON SOURCE LINES 73-82

.. code-block:: Python


    fig = plt.figure(figsize=(7, 1))
    text = fig.text(0.5, 0.5, 'This text stands out because of\n'
                              'its black border.', color='white',
                              ha='center', va='center', size=30)
    text.set_path_effects([path_effects.Stroke(linewidth=3, foreground='black'),
                           path_effects.Normal()])
    plt.show()




.. image-sg:: /users/explain/artists/images/sphx_glr_patheffects_guide_003.png
   :alt: patheffects guide
   :srcset: /users/explain/artists/images/sphx_glr_patheffects_guide_003.png, /users/explain/artists/images/sphx_glr_patheffects_guide_003_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 83-105

It is important to note that this effect only works because we have drawn
the text path twice; once with a thick black line, and then once with the
original text path on top.

You may have noticed that the keywords to `Stroke` and `SimplePatchShadow`
and `SimpleLineShadow` are not the usual Artist keywords (*facecolor*
*edgecolor*, etc.). This is because with these path effects we are operating
at lower level of Matplotlib. In fact, the keywords which are accepted are
those for a `matplotlib.backend_bases.GraphicsContextBase` instance, which
have been designed for making it easy to create new backends - and not for
its user interface.


Greater control of the path effect Artist
-----------------------------------------

As already mentioned, some of the path effects operate at a lower level
than most users will be used to, meaning that setting keywords such as
*facecolor* and *edgecolor* raise an AttributeError. Luckily there is a
generic `PathPatchEffect` path effect which creates a `.patches.PathPatch`
class with the original path.  The keywords to this effect are identical to
those of `.patches.PathPatch`:

.. GENERATED FROM PYTHON SOURCE LINES 105-115

.. code-block:: Python


    fig = plt.figure(figsize=(8.5, 1))
    t = fig.text(0.02, 0.5, 'Hatch shadow', fontsize=75, weight=1000, va='center')
    t.set_path_effects([
        path_effects.PathPatchEffect(
            offset=(4, -4), hatch='xxxx', facecolor='gray'),
        path_effects.PathPatchEffect(
            edgecolor='white', linewidth=1.1, facecolor='black')])
    plt.show()




.. image-sg:: /users/explain/artists/images/sphx_glr_patheffects_guide_004.png
   :alt: patheffects guide
   :srcset: /users/explain/artists/images/sphx_glr_patheffects_guide_004.png, /users/explain/artists/images/sphx_glr_patheffects_guide_004_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 116-124

..
    Headings for future consideration:

    Implementing a custom path effect
    ---------------------------------

    What is going on under the hood
    --------------------------------


.. _sphx_glr_download_users_explain_artists_patheffects_guide.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: patheffects_guide.ipynb <patheffects_guide.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: patheffects_guide.py <patheffects_guide.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: patheffects_guide.zip <patheffects_guide.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
