matplotlib.text#

Classes for including text in a figure.

class matplotlib.text.Text(x=0, y=0, text='', *, color=None, verticalalignment='baseline', horizontalalignment='left', multialignment=None, fontproperties=None, rotation=None, linespacing=None, rotation_mode=None, usetex=None, wrap=False, transform_rotates_text=False, parse_math=None, antialiased=None, **kwargs)[source]#

Bases: Artist

Handle storing and drawing of text in window or data coordinates.

Create a Text instance at x, y with string text.

The text is aligned relative to the anchor point (x, y) according to horizontalalignment (default: 'left') and verticalalignment (default: 'baseline'). See also Text alignment.

While Text accepts the 'label' keyword argument, by default it is not added to the handles of a legend.

Valid keyword arguments are:

Property

Description

agg_filter

a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image

alpha

scalar or None

animated

bool

antialiased

bool

backgroundcolor

color

bbox

dict with properties for patches.FancyBboxPatch

clip_box

unknown

clip_on

unknown

clip_path

unknown

color or c

color

figure

Figure

fontfamily or family or fontname

{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}

fontproperties or font or font_properties

font_manager.FontProperties or str or pathlib.Path

fontsize or size

float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

fontstretch or stretch

{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}

fontstyle or style

{'normal', 'italic', 'oblique'}

fontvariant or variant

{'normal', 'small-caps'}

fontweight or weight

{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}

gid

str

horizontalalignment or ha

{'left', 'center', 'right'}

in_layout

bool

label

object

linespacing

float (multiple of font size)

math_fontfamily

str

mouseover

bool

multialignment or ma

{'left', 'right', 'center'}

parse_math

bool

path_effects

list of AbstractPathEffect

picker

None or bool or float or callable

position

(float, float)

rasterized

bool

rotation

float or {'vertical', 'horizontal'}

rotation_mode

{None, 'default', 'anchor'}

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

text

object

transform

Transform

transform_rotates_text

bool

url

str

usetex

bool or None

verticalalignment or va

{'baseline', 'bottom', 'center', 'center_baseline', 'top'}

visible

bool

wrap

bool

x

float

y

float

zorder

float

contains(mouseevent)[source]#

Return whether the mouse event occurred inside the axis-aligned bounding-box of the text.

draw(renderer)[source]#

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:
rendererRendererBase subclass.

Notes

This method is overridden in the Artist subclasses.

get_antialiased()[source]#

Return whether antialiased rendering is used.

get_bbox_patch()[source]#

Return the bbox Patch, or None if the patches.FancyBboxPatch is not made.

get_c()[source]#

Alias for get_color.

get_color()[source]#

Return the color of the text.

get_family()[source]#

Alias for get_fontfamily.

get_font()[source]#

Alias for get_fontproperties.

get_font_properties()[source]#

Alias for get_fontproperties.

get_fontfamily()[source]#

Return the list of font families used for font lookup.

get_fontname()[source]#

Return the font name as a string.

get_fontproperties()[source]#

Return the font_manager.FontProperties.

get_fontsize()[source]#

Return the font size as an integer.

get_fontstyle()[source]#

Return the font style as a string.

get_fontvariant()[source]#

Return the font variant as a string.

get_fontweight()[source]#

Return the font weight as a string or a number.

get_ha()[source]#

Alias for get_horizontalalignment.

get_horizontalalignment()[source]#

Return the horizontal alignment as a string. Will be one of 'left', 'center' or 'right'.

get_math_fontfamily()[source]#

Return the font family name for math text rendered by Matplotlib.

The default value is rcParams["mathtext.fontset"] (default: 'dejavusans').

get_name()[source]#

Alias for get_fontname.

get_parse_math()[source]#

Return whether mathtext parsing is considered for this Text.

get_position()[source]#

Return the (x, y) position of the text.

get_rotation()[source]#

Return the text angle in degrees between 0 and 360.

get_rotation_mode()[source]#

Return the text rotation mode.

get_size()[source]#

Alias for get_fontsize.

get_stretch()[source]#

Return the font stretch as a string or a number.

get_style()[source]#

Alias for get_fontstyle.

get_text()[source]#

Return the text string.

get_transform_rotates_text()[source]#

Return whether rotations of the transform affect the text direction.

get_unitless_position()[source]#

Return the (x, y) unitless position of the text.

get_usetex()[source]#

Return whether this Text object uses TeX for rendering.

get_va()[source]#

Alias for get_verticalalignment.

get_variant()[source]#

Alias for get_fontvariant.

get_verticalalignment()[source]#

Return the vertical alignment as a string. Will be one of 'top', 'center', 'bottom', 'baseline' or 'center_baseline'.

get_weight()[source]#

Alias for get_fontweight.

get_window_extent(renderer=None, dpi=None)[source]#

Return the Bbox bounding the text, in display units.

In addition to being used internally, this is useful for specifying clickable regions in a png file on a web page.

Parameters:
rendererRenderer, optional

A renderer is needed to compute the bounding box. If the artist has already been drawn, the renderer is cached; thus, it is only necessary to pass this argument when calling get_window_extent before the first draw. In practice, it is usually easier to trigger a draw first, e.g. by calling draw_without_rendering or plt.show().

dpifloat, optional

The dpi value for computing the bbox, defaults to self.figure.dpi (not the renderer dpi); should be set e.g. if to match regions with a figure saved with a custom dpi value.

get_wrap()[source]#

Return whether the text can be wrapped.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, backgroundcolor=<UNSET>, bbox=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, fontfamily=<UNSET>, fontproperties=<UNSET>, fontsize=<UNSET>, fontstretch=<UNSET>, fontstyle=<UNSET>, fontvariant=<UNSET>, fontweight=<UNSET>, gid=<UNSET>, horizontalalignment=<UNSET>, in_layout=<UNSET>, label=<UNSET>, linespacing=<UNSET>, math_fontfamily=<UNSET>, mouseover=<UNSET>, multialignment=<UNSET>, parse_math=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, rasterized=<UNSET>, rotation=<UNSET>, rotation_mode=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, text=<UNSET>, transform=<UNSET>, transform_rotates_text=<UNSET>, url=<UNSET>, usetex=<UNSET>, verticalalignment=<UNSET>, visible=<UNSET>, wrap=<UNSET>, x=<UNSET>, y=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

Supported properties are

Property

Description

agg_filter

a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image

alpha

scalar or None

animated

bool

antialiased

bool

backgroundcolor

color

bbox

dict with properties for patches.FancyBboxPatch

clip_box

unknown

clip_on

unknown

clip_path

unknown

color

color

figure

Figure

fontfamily or fontname

{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}

fontproperties

font_manager.FontProperties or str or pathlib.Path

fontsize

float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

fontstretch

{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}

fontstyle

{'normal', 'italic', 'oblique'}

fontvariant

{'normal', 'small-caps'}

fontweight

{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}

gid

str

horizontalalignment

{'left', 'center', 'right'}

in_layout

bool

label

object

linespacing

float (multiple of font size)

math_fontfamily

str

mouseover

bool

multialignment

{'left', 'right', 'center'}

parse_math

bool

path_effects

list of AbstractPathEffect

picker

None or bool or float or callable

position

(float, float)

rasterized

bool

rotation

float or {'vertical', 'horizontal'}

rotation_mode

{None, 'default', 'anchor'}

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

text

object

transform

Transform

transform_rotates_text

bool

url

str

usetex

bool or None

verticalalignment

{'baseline', 'bottom', 'center', 'center_baseline', 'top'}

visible

bool

wrap

bool

x

float

y

float

zorder

float

set_antialiased(antialiased)[source]#

Set whether to use antialiased rendering.

Parameters:
antialiasedbool

Notes

Antialiasing will be determined by rcParams["text.antialiased"] (default: True) and the parameter antialiased will have no effect if the text contains math expressions.

set_backgroundcolor(color)[source]#

Set the background color of the text by updating the bbox.

Parameters:
colorcolor

See also

set_bbox

To change the position of the bounding box

set_bbox(rectprops)[source]#

Draw a bounding box around self.

Parameters:
rectpropsdict with properties for patches.FancyBboxPatch

The default boxstyle is 'square'. The mutation scale of the patches.FancyBboxPatch is set to the fontsize.

Examples

t.set_bbox(dict(facecolor='red', alpha=0.5))
set_c(color)[source]#

Alias for set_color.

set_clip_box(clipbox)[source]#

Set the artist's clip Bbox.

Parameters:
clipboxBboxBase or None

Will typically be created from a TransformedBbox. For instance, TransformedBbox(Bbox([[0, 0], [1, 1]]), ax.transAxes) is the default clipping for an artist added to an Axes.

set_clip_on(b)[source]#

Set whether the artist uses clipping.

When False, artists will be visible outside the Axes which can lead to unexpected results.

Parameters:
bbool
set_clip_path(path, transform=None)[source]#

Set the artist's clip path.

Parameters:
pathPatch or Path or TransformedPath or None

The clip path. If given a Path, transform must be provided as well. If None, a previously set clip path is removed.

transformTransform, optional

Only used if path is a Path, in which case the given Path is converted to a TransformedPath using transform.

Notes

For efficiency, if path is a Rectangle this method will set the clipping box to the corresponding rectangle and set the clipping path to None.

For technical reasons (support of set), a tuple (path, transform) is also accepted as a single positional parameter.

set_color(color)[source]#

Set the foreground color of the text

Parameters:
colorcolor
set_family(fontname)[source]#

Alias for set_fontfamily.

set_font(fp)[source]#

Alias for set_fontproperties.

set_font_properties(fp)[source]#

Alias for set_fontproperties.

set_fontfamily(fontname)[source]#

Set the font family. Can be either a single string, or a list of strings in decreasing priority. Each string may be either a real font name or a generic font class name. If the latter, the specific font names will be looked up in the corresponding rcParams.

If a Text instance is constructed with fontfamily=None, then the font is set to rcParams["font.family"] (default: ['sans-serif']), and the same is done when set_fontfamily() is called on an existing Text instance.

Parameters:
fontname{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
set_fontname(fontname)[source]#

Alias for set_fontfamily.

One-way alias only: the getter differs.

Parameters:
fontname{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
set_fontproperties(fp)[source]#

Set the font properties that control the text.

Parameters:
fpfont_manager.FontProperties or str or pathlib.Path

If a str, it is interpreted as a fontconfig pattern parsed by FontProperties. If a pathlib.Path, it is interpreted as the absolute path to a font file.

set_fontsize(fontsize)[source]#

Set the font size.

Parameters:
fontsizefloat or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

If a float, the fontsize in points. The string values denote sizes relative to the default font size.

set_fontstretch(stretch)[source]#

Set the font stretch (horizontal condensation or expansion).

Parameters:
stretch{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
set_fontstyle(fontstyle)[source]#

Set the font style.

Parameters:
fontstyle{'normal', 'italic', 'oblique'}
set_fontvariant(variant)[source]#

Set the font variant.

Parameters:
variant{'normal', 'small-caps'}
set_fontweight(weight)[source]#

Set the font weight.

Parameters:
weight{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
set_ha(align)[source]#

Alias for set_horizontalalignment.

set_horizontalalignment(align)[source]#

Set the horizontal alignment relative to the anchor point.

See also Text alignment.

Parameters:
align{'left', 'center', 'right'}
set_linespacing(spacing)[source]#

Set the line spacing as a multiple of the font size.

The default line spacing is 1.2.

Parameters:
spacingfloat (multiple of font size)
set_ma(align)[source]#

Alias for set_multialignment.

set_math_fontfamily(fontfamily)[source]#

Set the font family for math text rendered by Matplotlib.

This does only affect Matplotlib's own math renderer. It has no effect when rendering with TeX (usetex=True).

Parameters:
fontfamilystr

The name of the font family.

Available font families are defined in the default matplotlibrc file.

set_multialignment(align)[source]#

Set the text alignment for multiline texts.

The layout of the bounding box of all the lines is determined by the horizontalalignment and verticalalignment properties. This property controls the alignment of the text lines within that box.

Parameters:
align{'left', 'right', 'center'}
set_name(fontname)[source]#

Alias for set_fontname.

set_parse_math(parse_math)[source]#

Override switch to disable any mathtext parsing for this Text.

Parameters:
parse_mathbool

If False, this Text will never use mathtext. If True, mathtext will be used if there is an even number of unescaped dollar signs.

set_position(xy)[source]#

Set the (x, y) position of the text.

Parameters:
xy(float, float)
set_rotation(s)[source]#

Set the rotation of the text.

Parameters:
sfloat or {'vertical', 'horizontal'}

The rotation angle in degrees in mathematically positive direction (counterclockwise). 'horizontal' equals 0, 'vertical' equals 90.

set_rotation_mode(m)[source]#

Set text rotation mode.

Parameters:
m{None, 'default', 'anchor'}

If "default", the text will be first rotated, then aligned according to their horizontal and vertical alignments. If "anchor", then alignment occurs before rotation. Passing None will set the rotation mode to "default".

set_size(fontsize)[source]#

Alias for set_fontsize.

set_stretch(stretch)[source]#

Alias for set_fontstretch.

set_style(fontstyle)[source]#

Alias for set_fontstyle.

set_text(s)[source]#

Set the text string s.

It may contain newlines (\n) or math in LaTeX syntax.

Parameters:
sobject

Any object gets converted to its str representation, except for None which is converted to an empty string.

set_transform_rotates_text(t)[source]#

Whether rotations of the transform affect the text direction.

Parameters:
tbool
set_usetex(usetex)[source]#
Parameters:
usetexbool or None

Whether to render using TeX, None means to use rcParams["text.usetex"] (default: False).

set_va(align)[source]#

Alias for set_verticalalignment.

set_variant(variant)[source]#

Alias for set_fontvariant.

set_verticalalignment(align)[source]#

Set the vertical alignment relative to the anchor point.

See also Text alignment.

Parameters:
align{'baseline', 'bottom', 'center', 'center_baseline', 'top'}
set_weight(weight)[source]#

Alias for set_fontweight.

set_wrap(wrap)[source]#

Set whether the text can be wrapped.

Parameters:
wrapbool

Notes

Wrapping does not work together with savefig(..., bbox_inches='tight') (which is also used internally by %matplotlib inline in IPython/Jupyter). The 'tight' setting rescales the canvas to accommodate all content and happens before wrapping.

set_x(x)[source]#

Set the x position of the text.

Parameters:
xfloat
set_y(y)[source]#

Set the y position of the text.

Parameters:
yfloat
update(kwargs)[source]#

Update this artist's properties from the dict props.

Parameters:
propsdict
update_bbox_position_size(renderer)[source]#

Update the location and the size of the bbox.

This method should be used when the position and size of the bbox needs to be updated before actually drawing the bbox.

update_from(other)[source]#

Copy properties from other to self.

zorder = 3#
class matplotlib.text.Annotation(text, xy, xytext=None, xycoords='data', textcoords=None, arrowprops=None, annotation_clip=None, **kwargs)[source]#

Bases: Text, _AnnotationBase

An Annotation is a Text that can refer to a specific position xy. Optionally an arrow pointing from the text to xy can be drawn.

Attributes:
xy

The annotated position.

xycoords

The coordinate system for xy.

arrow_patch

A FancyArrowPatch to point from xytext to xy.

Annotate the point xy with text text.

In the simplest form, the text is placed at xy.

Optionally, the text can be displayed in another position xytext. An arrow pointing from the text to the annotated point xy can then be added by defining arrowprops.

Parameters:
textstr

The text of the annotation.

xy(float, float)

The point (x, y) to annotate. The coordinate system is determined by xycoords.

xytext(float, float), default: xy

The position (x, y) to place the text at. The coordinate system is determined by textcoords.

xycoordssingle or two-tuple of str or Artist or Transform or callable, default: 'data'

The coordinate system that xy is given in. The following types of values are supported:

  • One of the following strings:

    Value

    Description

    'figure points'

    Points from the lower left of the figure

    'figure pixels'

    Pixels from the lower left of the figure

    'figure fraction'

    Fraction of figure from lower left

    'subfigure points'

    Points from the lower left of the subfigure

    'subfigure pixels'

    Pixels from the lower left of the subfigure

    'subfigure fraction'

    Fraction of subfigure from lower left

    'axes points'

    Points from lower left corner of axes

    'axes pixels'

    Pixels from lower left corner of axes

    'axes fraction'

    Fraction of axes from lower left

    'data'

    Use the coordinate system of the object being annotated (default)

    'polar'

    (theta, r) if not native 'data' coordinates

    Note that 'subfigure pixels' and 'figure pixels' are the same for the parent figure, so users who want code that is usable in a subfigure can use 'subfigure pixels'.

  • An Artist: xy is interpreted as a fraction of the artist's Bbox. E.g. (0, 0) would be the lower left corner of the bounding box and (0.5, 1) would be the center top of the bounding box.

  • A Transform to transform xy to screen coordinates.

  • A function with one of the following signatures:

    def transform(renderer) -> Bbox
    def transform(renderer) -> Transform
    

    where renderer is a RendererBase subclass.

    The result of the function is interpreted like the Artist and Transform cases above.

  • A tuple (xcoords, ycoords) specifying separate coordinate systems for x and y. xcoords and ycoords must each be of one of the above described types.

See Advanced annotation for more details.

textcoordssingle or two-tuple of str or Artist or Transform or callable, default: value of xycoords

The coordinate system that xytext is given in.

All xycoords values are valid as well as the following strings:

Value

Description

'offset points'

Offset, in points, from the xy value

'offset pixels'

Offset, in pixels, from the xy value

'offset fontsize'

Offset, relative to fontsize, from the xy value

arrowpropsdict, optional

The properties used to draw a FancyArrowPatch arrow between the positions xy and xytext. Defaults to None, i.e. no arrow is drawn.

For historical reasons there are two different ways to specify arrows, "simple" and "fancy":

Simple arrow:

If arrowprops does not contain the key 'arrowstyle' the allowed keys are:

Key

Description

width

The width of the arrow in points

headwidth

The width of the base of the arrow head in points

headlength

The length of the arrow head in points

shrink

Fraction of total length to shrink from both ends

?

Any FancyArrowPatch property

The arrow is attached to the edge of the text box, the exact position (corners or centers) depending on where it's pointing to.

Fancy arrow:

This is used if 'arrowstyle' is provided in the arrowprops.

Valid keys are the following FancyArrowPatch parameters:

Key

Description

arrowstyle

The arrow style

connectionstyle

The connection style

relpos

See below; default is (0.5, 0.5)

patchA

Default is bounding box of the text

patchB

Default is None

shrinkA

Default is 2 points

shrinkB

Default is 2 points

mutation_scale

Default is text size (in points)

mutation_aspect

Default is 1

?

Any FancyArrowPatch property

The exact starting point position of the arrow is defined by relpos. It's a tuple of relative coordinates of the text box, where (0, 0) is the lower left corner and (1, 1) is the upper right corner. Values <0 and >1 are supported and specify points outside the text box. By default (0.5, 0.5), so the starting point is centered in the text box.

annotation_clipbool or None, default: None

Whether to clip (i.e. not draw) the annotation when the annotation point xy is outside the axes area.

  • If True, the annotation will be clipped when xy is outside the axes.

  • If False, the annotation will always be drawn.

  • If None, the annotation will be clipped when xy is outside the axes and xycoords is 'data'.

**kwargs

Additional kwargs are passed to Text.

Returns:
Annotation
property anncoords#

The coordinate system to use for Annotation.xyann.

contains(mouseevent)[source]#

Return whether the mouse event occurred inside the axis-aligned bounding-box of the text.

draw(renderer)[source]#

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:
rendererRendererBase subclass.

Notes

This method is overridden in the Artist subclasses.

get_anncoords()[source]#

Return the coordinate system to use for Annotation.xyann.

See also xycoords in Annotation.

get_tightbbox(renderer=None)[source]#

Like Artist.get_window_extent, but includes any clipping.

Parameters:
rendererRendererBase subclass, optional

renderer that will be used to draw the figures (i.e. fig.canvas.get_renderer())

Returns:
Bbox or None

The enclosing bounding box (in figure pixel coordinates). Returns None if clipping results in no intersection.

get_window_extent(renderer=None)[source]#

Return the Bbox bounding the text, in display units.

In addition to being used internally, this is useful for specifying clickable regions in a png file on a web page.

Parameters:
rendererRenderer, optional

A renderer is needed to compute the bounding box. If the artist has already been drawn, the renderer is cached; thus, it is only necessary to pass this argument when calling get_window_extent before the first draw. In practice, it is usually easier to trigger a draw first, e.g. by calling draw_without_rendering or plt.show().

dpifloat, optional

The dpi value for computing the bbox, defaults to self.figure.dpi (not the renderer dpi); should be set e.g. if to match regions with a figure saved with a custom dpi value.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, anncoords=<UNSET>, annotation_clip=<UNSET>, antialiased=<UNSET>, backgroundcolor=<UNSET>, bbox=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, fontfamily=<UNSET>, fontproperties=<UNSET>, fontsize=<UNSET>, fontstretch=<UNSET>, fontstyle=<UNSET>, fontvariant=<UNSET>, fontweight=<UNSET>, gid=<UNSET>, horizontalalignment=<UNSET>, in_layout=<UNSET>, label=<UNSET>, linespacing=<UNSET>, math_fontfamily=<UNSET>, mouseover=<UNSET>, multialignment=<UNSET>, parse_math=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, rasterized=<UNSET>, rotation=<UNSET>, rotation_mode=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, text=<UNSET>, transform=<UNSET>, transform_rotates_text=<UNSET>, url=<UNSET>, usetex=<UNSET>, verticalalignment=<UNSET>, visible=<UNSET>, wrap=<UNSET>, x=<UNSET>, y=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

Supported properties are

Property

Description

agg_filter

a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image

alpha

scalar or None

animated

bool

anncoords

unknown

annotation_clip

bool or None

antialiased

bool

backgroundcolor

color

bbox

dict with properties for patches.FancyBboxPatch

clip_box

BboxBase or None

clip_on

bool

clip_path

Patch or (Path, Transform) or None

color or c

color

figure

unknown

fontfamily or family or fontname

{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}

fontproperties or font or font_properties

font_manager.FontProperties or str or pathlib.Path

fontsize or size

float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

fontstretch or stretch

{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}

fontstyle or style

{'normal', 'italic', 'oblique'}

fontvariant or variant

{'normal', 'small-caps'}

fontweight or weight

{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}

gid

str

horizontalalignment or ha

{'left', 'center', 'right'}

in_layout

bool

label

object

linespacing

float (multiple of font size)

math_fontfamily

str

mouseover

bool

multialignment or ma

{'left', 'right', 'center'}

parse_math

bool

path_effects

list of AbstractPathEffect

picker

None or bool or float or callable

position

(float, float)

rasterized

bool

rotation

float or {'vertical', 'horizontal'}

rotation_mode

{None, 'default', 'anchor'}

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

text

object

transform

Transform

transform_rotates_text

bool

url

str

usetex

bool or None

verticalalignment or va

{'baseline', 'bottom', 'center', 'center_baseline', 'top'}

visible

bool

wrap

bool

x

float

y

float

zorder

float

set_anncoords(coords)[source]#

Set the coordinate system to use for Annotation.xyann.

See also xycoords in Annotation.

set_figure(fig)[source]#

Set the Figure instance the artist belongs to.

Parameters:
figFigure
update_positions(renderer)[source]#

Update the pixel positions of the annotation text and the arrow patch.

property xyann#

The text position.

See also xytext in Annotation.

property xycoords#
class matplotlib.text.OffsetFrom(artist, ref_coord, unit='points')[source]#

Bases: object

Callable helper class for working with Annotation.

Parameters:
artistArtist or BboxBase or Transform

The object to compute the offset from.

ref_coord(float, float)

If artist is an Artist or BboxBase, this values is the location to of the offset origin in fractions of the artist bounding box.

If artist is a transform, the offset origin is the transform applied to this value.

unit{'points, 'pixels'}, default: 'points'

The screen units to use (pixels or points) for the offset input.

get_unit()[source]#

Return the unit for input to the transform used by __call__.

set_unit(unit)[source]#

Set the unit for input to the transform used by __call__.

Parameters:
unit{'points', 'pixels'}
class matplotlib.text.TextPath(xy, s, size=None, prop=None, _interpolation_steps=1, usetex=False)[source]#

Bases: Path

Create a path from the text.

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:
xytuple or array of two float values

Position of the text. For no offset, use xy=(0, 0).

sstr

The text to convert to a path.

sizefloat, optional

Font size in points. Defaults to the size specified via the font properties prop.

propFontProperties, optional

Font property. If not provided, will use a default FontProperties with parameters from the rcParams.

_interpolation_stepsint, optional

(Currently ignored)

usetexbool, default: False

Whether to use tex rendering.

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.text 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)

Also see Using a text as a Path.

property codes#

Return the codes

get_size()[source]#

Get the text size.

set_size(size)[source]#

Set the text size.

property vertices#

Return the cached path after updating it if necessary.

class matplotlib.text.TextToPath[source]#

Bases: object

A class that converts strings to paths.

DPI = 72#
FONT_SCALE = 100.0#
get_glyphs_mathtext(prop, s, glyph_map=None, return_new_glyphs_only=False)[source]#

Parse mathtext string s and convert it to a (vertices, codes) pair.

get_glyphs_tex(prop, s, glyph_map=None, return_new_glyphs_only=False)[source]#

Convert the string s to vertices and codes using usetex mode.

get_glyphs_with_font(font, s, glyph_map=None, return_new_glyphs_only=False)[source]#

Convert string s to vertices and codes using the provided ttf font.

get_text_path(prop, s, ismath=False)[source]#

Convert text s to path (a tuple of vertices and codes for matplotlib.path.Path).

Parameters:
propFontProperties

The font properties for the text.

sstr

The text to be converted.

ismath{False, True, "TeX"}

If True, use mathtext parser. If "TeX", use tex for rendering.

Returns:
vertslist

A list of arrays containing the (x, y) coordinates of the vertices.

codeslist

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.text import TextToPath
from matplotlib.font_manager import FontProperties

fp = FontProperties(family="Comic Neue", 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.

get_text_width_height_descent(s, prop, ismath)[source]#