8000 document-textpath · matplotlib/matplotlib@81583be · GitHub
[go: up one dir, main page]
Skip to content

Commit 81583be

Browse files
ImportanceOfBeingErnestImportanceOfBeingErnest
committed
document-textpath
1 parent 36bc620 commit 81583be

File tree

5 files changed

+93
-19
lines changed

5 files changed

+93
-19
lines changed

‎doc/api/api_overview.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ Further reading:
3838
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
3939
plotting functions.
4040
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
41-
(except for the pyplot section).
41+
(except for the pyplot section)
42+
- The list of :doc:`matplotlib modules </api/index>`.
4243

4344

4445
The pylab API (disapproved)

‎doc/api/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ Modules
5555
style_api.rst
5656
table_api.rst
5757
text_api.rst
58+
textpath_api.rst
5859
ticker_api.rst
5960
tight_layout_api.rst
6061
transformations.rst

‎doc/api/textpath_api.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
********
2+
textpath
3+
********
4+
5+
6+
:mod:`matplotlib.textpath`
7+
==========================
8+
9+
.. automodule:: matplotlib.textpath
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:

‎examples/text_labels_and_annotations/demo_text_path.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
Demo Text Path
44
==============
55
6+
Use a text as `Path`. The tool that allows for such conversion is a
7+
`~matplotlib.textpath.TextPath`. The resulting path can be employed
8+
e.g. as a clip path for an image.
69
"""
710

811
import matplotlib.pyplot as plt

‎lib/matplotlib/textpath.py

Lines changed: 75 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -104,22 +104,46 @@ def get_text_width_height_descent(self, s, prop, ismath):
104104

105105
def get_text_path(self, prop, s, ismath=False, usetex=False):
106106
"""
107-
convert text *s* to path (a tuple of vertices and codes for
107+
Convert text *s* to path (a tuple of vertices and codes for
108108
matplotlib.path.Path).
109109
110-
*prop*
111-
font property
110+
Parameters
111+
----------
112112
113-
*s*
114-
text to be converted
113+
prop : `matplotlib.font_manager.FontProperties` instance
114+
The font properties for the text.
115115
116-
*usetex*
117-
If True, use matplotlib usetex mode.
116+
s : string
117+
The text to be converted.
118+
119+
usetex : bool
120+
If True, use matplotlib usetex mode.
118121
119-
*ismath*
120-
If True, use mathtext parser. Effective only if usetex == False.
122+
ismath : bool
123+
If True, use mathtext parser. Effective only if usetex == False.
121124
125+
Returns
126+
-------
122127
128+
verts, codes : tuple of lists
129+
*verts* is a list of numpy arrays containing the x and y
130+
coordinates of the vertices. *codes* is a list of path codes.
131+
132+
Examples
133+
--------
134+
135+
Create a list of vertices and codes from a text, and create a `Path`
136+
from those::
137+
138+
from matplotlib.path import Path
139+
from matplotlib.textpath import TextToPath
140+
from matplotlib.font_manager import FontProperties
141+
142+
fp = FontProperties(family="Humor Sans", style="italic")
143+
verts, codes = TextToPath().get_text_path(fp, "ABC")
144+
path = Path(verts, codes, closed=False)
145+
146+
Also see `TextPath` for a more direct way to create a path from a text.
123147
"""
124148
if not usetex:
125149
if not ismath:
@@ -391,16 +415,49 @@ class TextPath(Path):
391415
def __init__(self, xy, s, size=None, prop=None,
392416
_interpolation_steps=1, usetex=False,
393417
*kl, **kwargs):
394-
"""
395-
Create a path from the text. No support for TeX yet. Note that
396-
it simply is a path, not an artist. You need to use the
397-
PathPatch (or other artists) to draw this path onto the
398-
canvas.
418+
r"""
419+
Create a path from the text. Note that it simply is a path,
420+
not an artist. You need to use the `~.PathPatch` (or other artists)
421+
to draw this path onto the canvas.
422+
423+
Parameters
424+
----------
425+
426+
xy : tuple or array of two float values
427+
Position of the text. For no offset, use ``xy=(0,0)``.
428+
429+
s : string
430+
The text to convert to a path.
431+
432+
size : float, optional
433+
Font size in points. Defaults to the size specified via the font
434+
properties *prop*.
435+
436+
prop : `matplotlib.font_manager.FontProperties`, optional
437+
Font property. If not provided, will use a default
438+
``FontProperties`` with parameters from the
439+
:ref:`rcParams <matplotlib-rcparams>`.
440+
441+
_interpolation_steps : integer, optional
442+
(Currently ignored)
443+
444+
usetex : bool, optional
445+
Whether to use tex rendering. Defaults to ``False``.
446+
447+
Examples
448+
--------
449+
450+
The following creates a path from the string "ABC" with Helvetica
451+
font face; and another path from the latex fraction 1/2::
452+
453+
from matplotlib.textpath import TextPath
454+
from matplotlib.font_manager import FontProperties
455+
456+
fp = FontProperties(family="Helvetica", style="italic")
457+
path1 = TextPath((12,12), "ABC", size=12, prop=fp)
458+
path2 = TextPath((0,0), r"$\frac{1}{2}$", size=12, usetex=True)
399459
400-
xy : position of the text.
401-
s : text
402-
size : font size
403-
prop : font property
460+
Also see :doc:`/gallery/text_labels_and_annotations/demo_text_path`.
404461
"""
405462

406463
if prop is None:

0 commit comments

Comments
 (0)
0