mplsoccer.text module

mplsoccer’s text artists.

The module contains CurvedText, which draws text along a circular arc and is used by the radar and pizza charts to render curved parameter labels.

CurvedText author: PGupta-Git (https://github.com/PGupta-Git)

class mplsoccer.text.CurvedText(ax, x: float, y: float, s: str, *, center: tuple[float, float] | None = None, align: Literal['center', 'start', 'end'] = 'center', direction: Literal['auto', 'clockwise', 'counterclockwise'] = 'auto', radial_anchor: Literal['inner', 'center'] = 'inner', letter_spacing: float = 0.0, **kwargs)

Bases: Artist

Draw text along a circular arc for mplsoccer radar charts.

Parameters:

• ax (matplotlib axis) – The axis to plot on. Both Cartesian and polar axes are supported.

• x, y (float) – The position to place the text in data coordinates, with the same meaning as matplotlib’s Axes.text. On a Cartesian axis, the text curves along the circle through (x, y) around center, with the line of text vertically centered on the circle; the position must differ from center. On a polar axis (e.g. a pizza chart), x is the angle theta in radians and y is the radius, and the text curves along the circle of that radius around the polar origin.

• s (str) – The text to draw. Newlines split the text into multiple arcs stacked radially (see radial_anchor).

• center (tuple of float, optional) – The point the text curves around, in data coordinates. Defaults to (0, 0). Only valid on Cartesian axes: on polar axes the text always curves around the polar origin, and passing center raises a ValueError.

• align ({‘center’, ‘start’, ‘end’}, default ‘center’) – How to align the text relative to (x, y). 'start' and 'end' refer to the text’s reading direction along the arc rather than left/right, because direction='auto' can flip the direction the text flows.

• direction ({‘auto’, ‘clockwise’, ‘counterclockwise’}, default ‘auto’) – Direction to lay out characters along the arc. 'auto' flips direction in the lower half of the circle so the text stays readable.

• radial_anchor ({‘inner’, ‘center’}, default ‘inner’) – How multiline text stacks relative to the circle through (x, y): 'inner' centers the innermost line on the circle with further lines stacking outward, while 'center' centers the whole block of lines on the circle. Single-line text is centered on the circle either way.

• letter_spacing (float, default 0) – Additional spacing between characters in points, added on top of the font’s natural character widths. The default of 0 uses the font’s normal spacing; negative values tighten it.

• **kwargs (All other keyword arguments are passed on to matplotlib.axes.Axes.text.) – Arguments that do not translate to per-glyph curved layout (e.g. rotation and the alignment arguments) are ignored with a warning.

Notes

• Mathtext/TeX rendering is disabled for curved text (it is non-trivial to support when placing per-character glyphs along an arc).

• The layout mixes three unit systems, named by variable suffix: _data (data coordinates, where the arc is defined), _px (display pixels, where text sizes are known) and _pt (points, 1/72 inch, where font metrics are known). Each character’s angular step along the arc is its pixel width divided by the pixel radius (an angle is an arc length over a radius).

• An ‘advance’ is a font’s per-character pen movement: the width a character occupies, including the small side bearings around its ink. Glyphs are spaced by their advances, like normal text.

• The data-to-pixel scale is measured from the axes transform on every draw rather than assumed, so unequal aspect ratios, inverted axes and figure resizes are handled.

• On polar axes the arc geometry (theta offset, theta direction and the origin radius) is also read from the axes on every draw, so the text stays correct if the axes are reconfigured after it is created.

Attributes:

axes

The ~.axes.Axes instance the artist resides in, or None.

figure

The (Sub)Figure that the artist is on.

mouseover

Return whether this artist is queried for custom context information when the mouse cursor moves over it.

stale

Whether the artist is ‘stale’ and needs to be re-drawn for the output to match the internal state of the artist.

sticky_edges

x and y sticky edge lists for autoscaling.

Methods

add_callback(func)	Add a callback function that will be called whenever one of the .Artist's properties changes.
contains(mouseevent)	Return whether a mouse click or hover is over any of the glyphs, so curved labels respond to interactive events like regular text.
convert_xunits(x)	Convert x using the unit type of the xaxis.
convert_yunits(y)	Convert y using the unit type of the yaxis.
draw(renderer)	Position the glyphs for the current axes transform, then draw them.
findobj([match, include_self])	Find artist objects.
format_cursor_data(data)	Return a string representation of data.
get_agg_filter()	Return filter function to be used for agg filter.
get_alpha()	Return the transparency.
get_animated()	Return whether the artist is animated.
get_children()	Return the glyph patches, rebuilding them first if stale.
get_clip_box()	Return the clipbox.
get_clip_on()	Return whether the artist uses clipping.
get_clip_path()	Return the clip path.
get_color()	Return the text color.
get_cursor_data(event)	Return the cursor data for a given event.
get_figure([root])	Return the .Figure or .SubFigure instance the artist belongs to.
get_fontsize()	Return the font size in points.
get_gid()	Return the group id.
get_in_layout()	Return boolean flag, True if artist is included in layout calculations.
get_label()	Return the label used for this artist in the legend.
get_mouseover()	Return whether this artist is queried for custom context information when the mouse cursor moves over it.
get_picker()	Return the picking behavior of the artist.
get_rasterized()	Return whether the artist is to be rasterized.
get_sketch_params()	Return the sketch parameters for the artist.
get_snap()	Return the snap setting.
get_text()	Return the text string.
get_tightbbox([renderer])	Get the artist's bounding box in display space, taking clipping into account.
get_transform()	Return the .Transform instance used by this artist.
get_transformed_clip_path_and_affine()	Return the clip path with the non-affine part of its transformation applied, and the remaining affine part of its transformation.
get_url()	Return the url.
get_visible()	Return the visibility.
get_window_extent([renderer])	Return the bounding box of the laid-out glyphs in display space.
get_zorder()	Return the artist's zorder.
have_units()	Return whether units are set on any axis.
is_transform_set()	Return whether the Artist has an explicitly set transform.
pchanged()	Call all of the registered callbacks.
pick(mouseevent)	Process a pick event.
pickable()	Return whether the artist is pickable.
properties()	Return a dictionary of all the properties of the artist.
remove()	Remove the artist from the figure if possible.
remove_callback(oid)	Remove a callback based on its observer id.
set(*[, agg_filter, alpha, animated, ...])	Set multiple properties at once.
set_agg_filter(filter_func)	Set the agg filter.
set_alpha(alpha)	Set the transparency, from 0 (invisible) to 1 (opaque).
set_animated(b)	Set whether the artist is intended to be used in an animation.
set_clip_box(clipbox)	Set the artist's clip .Bbox.
set_clip_on(b)	Set whether the artist uses clipping.
set_clip_path(path[, transform])	Set the artist's clip path.
set_color(color)	Set the text color.
set_figure(fig)	Set the .Figure or .SubFigure instance the artist belongs to.
set_fontsize(fontsize)	Set the font size in points.
set_gid(gid)	Set the (group) id for the artist.
set_in_layout(in_layout)	Set if artist is to be included in layout calculations, E.g.
set_label(s)	Set a label that will be displayed in the legend.
set_mouseover(mouseover)	Set whether this artist is queried for custom context information when the mouse cursor moves over it.
set_path_effects(path_effects)	Set the path effects.
set_picker(picker)	Define the picking behavior of the artist.
set_rasterized(rasterized)	Force rasterized (bitmap) drawing for vector graphics output.
set_sketch_params([scale, length, randomness])	Set the sketch parameters.
set_snap(snap)	Set the snapping behavior.
set_text(text)	Set the text string.
set_transform(t)	Set the artist transform.
set_url(url)	Set the url for the artist.
set_visible(b)	Set the artist's visibility.
set_zorder(level)	Set the zorder for the artist.
update(props)	[Discouraged] Update this artist's properties from the dictionary props.
update_from(other)	Copy properties from other to self.

get_path_effects

set_text(text: str) → None

Set the text string.

get_text() → str

Return the text string.

set_color(color) → None

Set the text color.

get_color()

Return the text color.

set_fontsize(fontsize) → None

Set the font size in points.

get_fontsize()

Return the font size in points.

set_alpha(alpha) → None

Set the transparency, from 0 (invisible) to 1 (opaque).

get_alpha()

Return the transparency.

get_children()

Return the glyph patches, rebuilding them first if stale.

draw(renderer) → None

Position the glyphs for the current axes transform, then draw them.

get_window_extent(renderer=None)

Return the bounding box of the laid-out glyphs in display space.

Implementing this lets curved labels participate in tight bounding box calculations (savefig(bbox_inches='tight'), tight_layout, constrained_layout) instead of reporting a zero-size box, which would crop the labels out of saved figures.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, fontsize=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, text=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Properties:

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: unknown animated: bool clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None color: unknown figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure fontsize: unknown gid: str in_layout: bool label: object mouseover: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None text: unknown transform: ~matplotlib.transforms.Transform url: str visible: bool zorder: float

contains(mouseevent)

Return whether a mouse click or hover is over any of the glyphs, so curved labels respond to interactive events like regular text.