diff --git a/doc/api/api_overview.rst b/doc/api/api_overview.rst index 0b735010cbdb..95c4af28d176 100644 --- a/doc/api/api_overview.rst +++ b/doc/api/api_overview.rst @@ -38,7 +38,8 @@ Further reading: - `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of plotting functions. - Most of the :ref:`examples ` use the object-oriented approach - (except for the pyplot section). + (except for the pyplot section) +- The list of :doc:`matplotlib modules `. The pylab API (disapproved) diff --git a/doc/api/index.rst b/doc/api/index.rst index 2646cb783bcd..0f29598795ea 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -55,6 +55,7 @@ Modules style_api.rst table_api.rst text_api.rst + textpath_api.rst ticker_api.rst tight_layout_api.rst transformations.rst diff --git a/doc/api/textpath_api.rst b/doc/api/textpath_api.rst new file mode 100644 index 000000000000..46e1e3884627 --- /dev/null +++ b/doc/api/textpath_api.rst @@ -0,0 +1,12 @@ +******** +textpath +******** + + +:mod:`matplotlib.textpath` +========================== + +.. automodule:: matplotlib.textpath + :members: + :undoc-members: + :show-inheritance: diff --git a/examples/text_labels_and_annotations/demo_text_path.py b/examples/text_labels_and_annotations/demo_text_path.py index d1e2d421b07c..ce63f3e47696 100644 --- a/examples/text_labels_and_annotations/demo_text_path.py +++ b/examples/text_labels_and_annotations/demo_text_path.py @@ -3,6 +3,9 @@ Demo Text Path ============== +Use a text as `Path`. The tool that allows for such conversion is a +`~matplotlib.textpath.TextPath`. The resulting path can be employed +e.g. as a clip path for an image. """ import matplotlib.pyplot as plt diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py index 2e7f92500ba7..3169532c23ce 100644 --- a/lib/matplotlib/textpath.py +++ b/lib/matplotlib/textpath.py @@ -104,22 +104,47 @@ def get_text_width_height_descent(self, s, prop, ismath): def get_text_path(self, prop, s, ismath=False, usetex=False): """ - convert text *s* to path (a tuple of vertices and codes for + Convert text *s* to path (a tuple of vertices and codes for matplotlib.path.Path). - *prop* - font property + Parameters + ---------- - *s* - text to be converted + prop : `matplotlib.font_manager.FontProperties` instance + The font properties for the text. - *usetex* - If True, use matplotlib usetex mode. + s : str + The text to be converted. - *ismath* - If True, use mathtext parser. Effective only if usetex == False. + usetex : bool, optional + Whether to use tex rendering. Defaults to ``False``. + ismath : bool, optional + If True, use mathtext parser. Effective only if + ``usetex == False``. + Returns + ------- + + verts, codes : tuple of lists + *verts* is a list of numpy arrays containing the x and y + coordinates of the vertices. *codes* is a list of path codes. + + Examples + -------- + + Create a list of vertices and codes from a text, and create a `Path` + from those:: + + from matplotlib.path import Path + from matplotlib.textpath import TextToPath + from matplotlib.font_manager import FontProperties + + fp = FontProperties(family="Humor Sans", style="italic") + verts, codes = TextToPath().get_text_path(fp, "ABC") + path = Path(verts, codes, closed=False) + + Also see `TextPath` for a more direct way to create a path from a text. """ if not usetex: if not ismath: @@ -392,16 +417,49 @@ class TextPath(Path): def __init__(self, xy, s, size=None, prop=None, _interpolation_steps=1, usetex=False, *kl, **kwargs): - """ - Create a path from the text. No support for TeX yet. Note that - it simply is a path, not an artist. You need to use the - PathPatch (or other artists) to draw this path onto the - canvas. + r""" + Create a path from the text. Note that it simply is a path, + not an artist. You need to use the `~.PathPatch` (or other artists) + to draw this path onto the canvas. + + Parameters + ---------- + + xy : tuple or array of two float values + Position of the text. For no offset, use ``xy=(0, 0)``. + + s : str + The text to convert to a path. + + size : float, optional + Font size in points. Defaults to the size specified via the font + properties *prop*. + + prop : `matplotlib.font_manager.FontProperties`, optional + Font property. If not provided, will use a default + ``FontProperties`` with parameters from the + :ref:`rcParams `. + + _interpolation_steps : integer, optional + (Currently ignored) + + usetex : bool, optional + Whether to use tex rendering. Defaults to ``False``. + + Examples + -------- + + The following creates a path from the string "ABC" with Helvetica + font face; and another path from the latex fraction 1/2:: + + from matplotlib.textpath import TextPath + from matplotlib.font_manager import FontProperties + + fp = FontProperties(family="Helvetica", style="italic") + path1 = TextPath((12,12), "ABC", size=12, prop=fp) + path2 = TextPath((0,0), r"$\frac{1}{2}$", size=12, usetex=True) - xy : position of the text. - s : text - size : font size - prop : font property + Also see :doc:`/gallery/text_labels_and_annotations/demo_text_path`. """ if prop is None: