contour

matplotlib.contour

These are classes to support contour plotting and labelling for the Axes class.

class matplotlib.contour.ClabelText(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, **kwargs)

Bases: matplotlib.text.Text

Unlike the ordinary text, the get_rotation returns an updated angle in the pixel coordinate assuming that the input rotation is an angle in data coordinate (or whatever transform set).

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

Valid kwargs 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
alpha	float
animated	bool
backgroundcolor	color
bbox	dict with properties for patches.FancyBboxPatch
clip_box	matplotlib.transforms.Bbox
clip_on	bool
clip_path	{ (path.Path, transforms.Transform), patches.Patch, None }
color	color
contains	callable
figure	Figure
fontfamily	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontname	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties	font_manager.FontProperties
fontsize	{size in points, '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	{'center', 'right', 'left'}
in_layout	bool
label	object
linespacing	float (multiple of font size)
multialignment	{'left', 'right', 'center'}
path_effects	AbstractPathEffect
picker	None or bool or float or callable
position	(float, float)
rasterized	bool or None
rotation	{angle in degrees, 'vertical', 'horizontal'}
rotation_mode	{None, 'default', 'anchor'}
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
text	string or object castable to string (but None becomes '')
transform	Transform
url	str
usetex	bool or None
verticalalignment	{'center', 'top', 'bottom', 'baseline', 'center_baseline'}
visible	bool
wrap	bool
x	float
y	float
zorder	float

get_rotation()

Return the text angle as float in degrees.

class matplotlib.contour.ContourLabeler

Bases: object

Mixin to provide labelling capability to ContourSet.

add_label(x, y, rotation, lev, cvalue)

Add contour label using Text class.

add_label_clabeltext(x, y, rotation, lev, cvalue)

Add contour label using ClabelText class.

add_label_near(x, y, inline=True, inline_spacing=5, transform=None)

Add a label near the point (x, y). If transform is None (default), (x, y) is in data coordinates; if transform is False, (x, y) is in display coordinates; otherwise, the specified transform will be used to translate (x, y) into display coordinates.

Parameters:

x, y : float

The approximate location of the label.

inline : bool, optional, default: True

If True remove the segment of the contour beneath the label.

inline_spacing : int, optional, default: 5

Space in pixels to leave on each side of label when placing inline. This spacing will be exact for labels at locations where the contour is straight, less so for labels on curved contours.

calc_label_rot_and_inline(slc, ind, lw, lc=None, spacing=5)

This function calculates the appropriate label rotation given the linecontour coordinates in screen units, the index of the label location and the label width.

It will also break contour and calculate inlining if lc is not empty (lc defaults to the empty list if None). spacing is the space around the label in pixels to leave empty.

Do both of these tasks at once to avoid calculating path lengths multiple times, which is relatively costly.

The method used here involves calculating the path length along the contour in pixel coordinates and then looking approximately label width / 2 away from central point to determine rotation and then to break contour if desired.

cl

Deprecated since version 3.0: The <lambda> function was deprecated in Matplotlib 3.0 and will be removed in 3.2. Use labelTexts instead.

cl_cvalues

Deprecated since version 3.0: The <lambda> function was deprecated in Matplotlib 3.0 and will be removed in 3.2. Use labelCValues instead.

cl_xy

Deprecated since version 3.0: The <lambda> function was deprecated in Matplotlib 3.0 and will be removed in 3.2. Use labelXYs instead.

clabel(*args, fontsize=None, inline=True, inline_spacing=5, fmt='%1.3f', colors=None, use_clabeltext=False, manual=False, rightside_up=True)

Label a contour plot.

Call signature:

clabel(cs, [levels,] **kwargs)

Adds labels to line contours in cs, where cs is a ContourSet object returned by contour().

Parameters:

cs : ContourSet

The ContourSet to label.

levels : array-like, optional

A list of level values, that should be labeled. The list must be a subset of cs.levels. If not given, all levels are labeled.

fontsize : string or float, optional

Size in points or relative size e.g., 'smaller', 'x-large'. See Text.set_size for accepted string values.

colors : color-spec, optional

The label colors:

• If None, the color of each label matches the color of the corresponding contour.
• If one string color, e.g., colors = 'r' or colors = 'red', all labels will be plotted in this color.
• If a tuple of matplotlib color args (string, float, rgb, etc), different labels will be plotted in different colors in the order specified.

inline : bool, optional

If True the underlying contour is removed where the label is placed. Default is True.

inline_spacing : float, optional

Space in pixels to leave on each side of label when placing inline. Defaults to 5.

This spacing will be exact for labels at locations where the contour is straight, less so for labels on curved contours.

fmt : string or dict, optional

A format string for the label. Default is '%1.3f'

Alternatively, this can be a dictionary matching contour levels with arbitrary strings to use for each contour level (i.e., fmt[level]=string), or it can be any callable, such as a Formatter instance, that returns a string when called with a numeric contour level.

manual : bool or iterable, optional

If True, contour labels will be placed manually using mouse clicks. Click the first button near a contour to add a label, click the second button (or potentially both mouse buttons at once) to finish adding labels. The third button can be used to remove the last label added, but only if labels are not inline. Alternatively, the keyboard can be used to select label locations (enter to end label placement, delete or backspace act like the third mouse button, and any other key will select a label location).

manual can also be an iterable object of x,y tuples. Contour labels will be created as if mouse is clicked at each x,y positions.

rightside_up : bool, optional

If True, label rotations will always be plus or minus 90 degrees from level. Default is True.

use_clabeltext : bool, optional

If True, ClabelText class (instead of Text) is used to create labels. ClabelText recalculates rotation angles of texts during the drawing time, therefore this can be used if aspect of the axes changes. Default is False.

Returns:

labels

A list of Text instances for the labels.

get_label_coords(distances, XX, YY, ysize, lw)

Return x, y, and the index of a label location.

Labels are plotted at a location with the smallest deviation of the contour from a straight line unless there is another label nearby, in which case the next best place on the contour is picked up. If all such candidates are rejected, the beginning of the contour is chosen.

get_label_width(lev, fmt, fsize)

Return the width of the label in points.

get_real_label_width(lev, fmt, fsize)

Deprecated since version 2.2: The get_real_label_width function was deprecated in Matplotlib 2.2 and will be removed in 3.1.

This computes actual onscreen label width. This uses some black magic to determine onscreen extent of non-drawn label. This magic may not be very robust.

This method is not being used, and may be modified or removed.

get_text(lev, fmt)

Get the text of the label.

labels(inline, inline_spacing)

locate_label(linecontour, labelwidth)

Find good place to draw a label (relatively flat part of the contour).

pop_label(index=-1)

Defaults to removing last label, but any index can be supplied

print_label(linecontour, labelwidth)

Return False if contours are too short for a label.

set_label_props(label, text, color)

Set the label properties - color, fontsize, text.

too_close(x, y, lw)

Return True if a label is already near this location.

class matplotlib.contour.ContourSet(ax, *args, levels=None, filled=False, linewidths=None, linestyles=None, alpha=None, origin=None, extent=None, cmap=None, colors=None, norm=None, vmin=None, vmax=None, extend='neither', antialiased=None, **kwargs)

Bases: matplotlib.cm.ScalarMappable, matplotlib.contour.ContourLabeler

Store a set of contour lines or filled regions.

User-callable method: clabel

Parameters:

ax : Axes

levels : [level0, level1, ..., leveln]

A list of floating point numbers indicating the contour levels.

allsegs : [level0segs, level1segs, ...]

List of all the polygon segments for all the levels. For contour lines len(allsegs) == len(levels), and for filled contour regions len(allsegs) = len(levels)-1. The lists should look like:

level0segs = [polygon0, polygon1, ...]
polygon0 = array_like [[x0,y0], [x1,y1], ...]

allkinds : None or [level0kinds, level1kinds, ...]

Optional list of all the polygon vertex kinds (code types), as described and used in Path. This is used to allow multiply- connected paths such as holes within filled polygons. If not None, len(allkinds) == len(allsegs). The lists should look like:

level0kinds = [polygon0kinds, ...]
polygon0kinds = [vertexcode0, vertexcode1, ...]

If allkinds is not None, usually all polygons for a particular contour level are grouped together so that level0segs = [polygon0] and level0kinds = [polygon0kinds].

kwargs :

Keyword arguments are as described in the docstring of contour.

Attributes:

ax:

The axes object in which the contours are drawn.

collections:

A silent_list of LineCollections or PolyCollections.

levels:

Contour levels.

layers:

Same as levels for line contours; half-way between levels for filled contours. See _process_colors().

Draw contour lines or filled regions, depending on whether keyword arg filled is False (default) or True.

Call signature:

ContourSet(ax, levels, allsegs, [allkinds], **kwargs)

Parameters:

ax :

The Axes object to draw on.

levels : [level0, level1, ..., leveln]

A list of floating point numbers indicating the contour levels.

allsegs : [level0segs, level1segs, ...]

List of all the polygon segments for all the levels. For contour lines len(allsegs) == len(levels), and for filled contour regions len(allsegs) = len(levels)-1. The lists should look like:

level0segs = [polygon0, polygon1, ...]
polygon0 = array_like [[x0,y0], [x1,y1], ...]

allkinds : [level0kinds, level1kinds, ...], optional

Optional list of all the polygon vertex kinds (code types), as described and used in Path. This is used to allow multiply- connected paths such as holes within filled polygons. If not None, len(allkinds) == len(allsegs). The lists should look like:

level0kinds = [polygon0kinds, ...]
polygon0kinds = [vertexcode0, vertexcode1, ...]

If allkinds is not None, usually all polygons for a particular contour level are grouped together so that level0segs = [polygon0] and level0kinds = [polygon0kinds].

**kwargs

Keyword arguments are as described in the docstring of contour.

changed()

Call this whenever the mappable is changed to notify all the callbackSM listeners to the 'changed' signal

find_nearest_contour(x, y, indices=None, pixel=True)

Finds contour that is closest to a point. Defaults to measuring distance in pixels (screen space - useful for manual contour labeling), but this can be controlled via a keyword argument.

Returns a tuple containing the contour, segment, index of segment, x & y of segment point and distance to minimum point.

Optional keyword arguments:

indices:

Indexes of contour levels to consider when looking for nearest point. Defaults to using all levels.

pixel:

If True, measure distance in pixel space, if not, measure distance in axes space. Defaults to True.

get_alpha()

returns alpha to be applied to all ContourSet artists

get_transform()

Return the Transform instance used by this ContourSet.

legend_elements(variable_name='x', str_format=<class 'str'>)

Return a list of artists and labels suitable for passing through to plt.legend() which represent this ContourSet.

The labels have the form "0 < x <= 1" stating the data ranges which the artists represent.

Parameters:

variable_name : str

The string used inside the inequality used on the labels.

str_format : function: float -> str

Function used to format the numbers in the labels.

Returns:

artists : List[Artist]

A list of the artists.

labels : List[str]

A list of the labels.

set_alpha(alpha)

Set the alpha blending value for all ContourSet artists. alpha must be between 0 (transparent) and 1 (opaque).

class matplotlib.contour.QuadContourSet(ax, *args, levels=None, filled=False, linewidths=None, linestyles=None, alpha=None, origin=None, extent=None, cmap=None, colors=None, norm=None, vmin=None, vmax=None, extend='neither', antialiased=None, **kwargs)

Bases: matplotlib.contour.ContourSet

Create and store a set of contour lines or filled regions.

User-callable method: clabel

Attributes:

ax:

The axes object in which the contours are drawn.

collections:

A silent_list of LineCollections or PolyCollections.

levels:

Contour levels.

layers:

Same as levels for line contours; half-way between levels for filled contours. See _process_colors() method.

Draw contour lines or filled regions, depending on whether keyword arg filled is False (default) or True.

Call signature:

ContourSet(ax, levels, allsegs, [allkinds], **kwargs)

Parameters:

ax :

The Axes object to draw on.

levels : [level0, level1, ..., leveln]

A list of floating point numbers indicating the contour levels.

allsegs : [level0segs, level1segs, ...]

List of all the polygon segments for all the levels. For contour lines len(allsegs) == len(levels), and for filled contour regions len(allsegs) = len(levels)-1. The lists should look like:

level0segs = [polygon0, polygon1, ...]
polygon0 = array_like [[x0,y0], [x1,y1], ...]

allkinds : [level0kinds, level1kinds, ...], optional

Optional list of all the polygon vertex kinds (code types), as described and used in Path. This is used to allow multiply- connected paths such as holes within filled polygons. If not None, len(allkinds) == len(allsegs). The lists should look like:

level0kinds = [polygon0kinds, ...]
polygon0kinds = [vertexcode0, vertexcode1, ...]

If allkinds is not None, usually all polygons for a particular contour level are grouped together so that level0segs = [polygon0] and level0kinds = [polygon0kinds].

**kwargs

Keyword arguments are as described in the docstring of contour.