artists

matplotlib.artist

class matplotlib.artist.Artist

Bases: object

Abstract base class for someone who renders into a FigureCanvas.

add_callback(func)

Adds a callback function that will be called whenever one of the Artist‘s properties changes.

Returns an id that is useful for removing the callback with remove_callback() later.

aname = 'Artist'

axes

The Axes instance the artist resides in, or None.

bottom_margin

Get whether a margin should be applied to the bottom of the Artist.

contains(mouseevent)

Test whether the artist contains the mouse event.

Returns the truth value and a dictionary of artist specific details of selection, such as which points are contained in the pick radius. See individual artists for details.

convert_xunits(x)

For artists in an axes, if the xaxis has units support, convert x using xaxis unit type

convert_yunits(y)

For artists in an axes, if the yaxis has units support, convert y using yaxis unit type

draw(renderer, *args, **kwargs)

Derived classes drawing method

findobj(match=None, include_self=True)

Find artist objects.

Recursively find all Artist instances contained in self.

match can be

• None: return all objects contained in artist.
• function with signature boolean = match(artist) used to filter matches
• class instance: e.g., Line2D. Only return artists of class type.

If include_self is True (default), include self in the list to be checked for a match.

format_cursor_data(data)

Return cursor data string formatted.

get_agg_filter()

return filter function to be used for agg filter

get_alpha()

Return the alpha value used for blending - not supported on all backends

get_animated()

Return the artist’s animated state

get_axes()

Return the Axes instance the artist resides in, or None.

This has been deprecated in mpl 1.5, please use the axes property. Will be removed in 1.7 or 2.0.

get_bottom_margin()

Get whether a margin should be applied to the bottom of the Artist.

get_children()

Return a list of the child Artist`s this :class:`Artist contains.

get_clip_box()

Return artist clipbox

get_clip_on()

Return whether artist uses clipping

get_clip_path()

Return artist clip path

get_contains()

Return the _contains test used by the artist, or None for default.

get_cursor_data(event)

Get the cursor data for a given event.

get_figure()

Return the Figure instance the artist belongs to.

get_gid()

Returns the group id

get_label()

Get the label used for this artist in the legend.

get_left_margin()

Get whether a margin should be applied to the left of the Artist.

get_margins()

Returns a dictionary describing whether a margin should be applied on each of the sides (top, bottom, left and right).

get_path_effects()

get_picker()

Return the picker object used by this artist

get_rasterized()

return True if the artist is to be rasterized

get_right_margin()

Get whether a margin should be applied to the right of the Artist.

get_sketch_params()

Returns the sketch parameters for the artist.

Returns:

sketch_params : tuple or None

A 3-tuple with the following elements:

• scale: The amplitude of the wiggle perpendicular to the source line.
• length: The length of the wiggle along the line.
• randomness: The scale factor by which the length is shrunken or expanded.

May return None if no sketch parameters were set.

get_snap()

Returns the snap setting which may be:

• True: snap vertices to the nearest pixel center
• False: leave vertices as-is
• None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center

Only supported by the Agg and MacOSX backends.

get_top_margin()

Get whether a margin should be applied to the top of the Artist.

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()

Returns the url

get_visible()

Return the artist’s visiblity

get_window_extent(renderer)

Get the axes bounding box in display space. Subclasses should override for inclusion in the bounding box “tight” calculation. Default is to return an empty bounding box at 0, 0.

Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.

get_zorder()

Return the Artist‘s zorder.

have_units()

Return True if units are set on the x or y axes

hitlist(event)

List the children of the artist which contain the mouse event event.

is_figure_set()

Returns True if the artist is assigned to a Figure.

is_transform_set()

Returns True if Artist has a transform explicitly set.

left_margin

Get whether a margin should be applied to the left of the Artist.

margins

Returns a dictionary describing whether a margin should be applied on each of the sides (top, bottom, left and right).

mouseover

pchanged()

Fire an event when property changed, calling all of the registered callbacks.

pick(mouseevent)

Process pick event

call signature:

pick(mouseevent)

each child artist will fire a pick event if mouseevent is over the artist and the artist has picker set

pickable()

Return True if Artist is pickable.

properties()

return a dictionary mapping property name -> value for all Artist props

remove()

Remove the artist from the figure if possible. The effect will not be visible until the figure is redrawn, e.g., with matplotlib.axes.Axes.draw_idle(). Call matplotlib.axes.Axes.relim() to update the axes limits if desired.

Note: relim() will not see collections even if the collection was added to axes with autolim = True.

Note: there is no support for removing the artist’s legend entry.

remove_callback(oid)

Remove a callback based on its id.

See also

add_callback()

For adding callbacks

right_margin

Get whether a margin should be applied to the right of the Artist.

set(**kwargs)

A property batch setter. Pass kwargs to set properties.

set_agg_filter(filter_func)

set agg_filter fuction.

set_alpha(alpha)

Set the alpha value used for blending - not supported on all backends.

ACCEPTS: float (0.0 transparent through 1.0 opaque)

set_animated(b)

Set the artist’s animation state.

ACCEPTS: [True | False]

set_axes(axes)

Set the Axes instance in which the artist resides, if any.

This has been deprecated in mpl 1.5, please use the axes property. Will be removed in 1.7 or 2.0.

ACCEPTS: an Axes instance

set_bottom_margin(margin)

Set whether a margin should be applied to the bottom of the Artist.

set_clip_box(clipbox)

Set the artist’s clip Bbox.

ACCEPTS: a matplotlib.transforms.Bbox instance

set_clip_on(b)

Set whether artist uses clipping.

When False artists will be visible out side of the axes which can lead to unexpected results.

ACCEPTS: [True | False]

set_clip_path(path, transform=None)

Set the artist’s clip path, which may be:

• a Patch (or subclass) instance

• a Path instance, in which case

  an optional Transform instance may be provided, which will be applied to the path before using it for clipping.

• None, to remove the clipping path

For efficiency, if the path happens to be an axis-aligned rectangle, this method will set the clipping box to the corresponding rectangle and set the clipping path to None.

ACCEPTS: [ (Path, Transform) | Patch | None ]

set_contains(picker)

Replace the contains test used by this artist. The new picker should be a callable function which determines whether the artist is hit by the mouse event:

hit, props = picker(artist, mouseevent)

If the mouse event is over the artist, return hit = True and props is a dictionary of properties you want returned with the contains test.

ACCEPTS: a callable function

set_figure(fig)

Set the Figure instance the artist belongs to.

ACCEPTS: a matplotlib.figure.Figure instance

set_gid(gid)

Sets the (group) id for the artist

ACCEPTS: an id string

set_label(s)

Set the label to s for auto legend.

ACCEPTS: string or anything printable with ‘%s’ conversion.

set_left_margin(margin)

Set whether a margin should be applied to the left of the Artist.

set_margins(margins)

Set the dictionary describing whether a margin should be applied on each of the sides (top, bottom, left and right). Missing keys are assumed to be True. If True or False are passed in, all sides are set to that value.

set_path_effects(path_effects)

set path_effects, which should be a list of instances of matplotlib.patheffect._Base class or its derivatives.

set_picker(picker)

Set the epsilon for picking used by this artist

picker can be one of the following:

• None: picking is disabled for this artist (default)

• A boolean: if True then picking will be enabled and the artist will fire a pick event if the mouse event is over the artist

• A float: if picker is a number it is interpreted as an epsilon tolerance in points and the artist will fire off an event if it’s data is within epsilon of the mouse event. For some artists like lines and patch collections, the artist may provide additional data to the pick event that is generated, e.g., the indices of the data within epsilon of the pick event

• A function: if picker is callable, it is a user supplied function which determines whether the artist is hit by the mouse event:

  hit, props = picker(artist, mouseevent)
  

  to determine the hit test. if the mouse event is over the artist, return hit=True and props is a dictionary of properties you want added to the PickEvent attributes.

ACCEPTS: [None|float|boolean|callable]

set_rasterized(rasterized)

Force rasterized (bitmap) drawing in vector backend output.

Defaults to None, which implies the backend’s default behavior

ACCEPTS: [True | False | None]

set_right_margin(margin)

Set whether a margin should be applied to the right of the Artist.

set_sketch_params(scale=None, length=None, randomness=None)

Sets the sketch parameters.

Parameters:

scale : float, optional

The amplitude of the wiggle perpendicular to the source line, in pixels. If scale is None, or not provided, no sketch filter will be provided.

length : float, optional

The length of the wiggle along the line, in pixels (default 128.0)

randomness : float, optional

The scale factor by which the length is shrunken or expanded (default 16.0)

set_snap(snap)

Sets the snap setting which may be:

• True: snap vertices to the nearest pixel center
• False: leave vertices as-is
• None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center

Only supported by the Agg and MacOSX backends.

set_top_margin(margin)

Set whether a margin should be applied to the top of the Artist.

set_transform(t)

Set the Transform instance used by this artist.

ACCEPTS: Transform instance

set_url(url)

Sets the url for the artist

ACCEPTS: a url string

set_visible(b)

Set the artist’s visiblity.

ACCEPTS: [True | False]

set_zorder(level)

Set the zorder for the artist. Artists with lower zorder values are drawn first.

ACCEPTS: any number

stale

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

top_margin

Get whether a margin should be applied to the top of the Artist.

update(props)

Update the properties of this Artist from the dictionary prop.

update_from(other)

Copy properties from other to self.

zorder = 0

class matplotlib.artist.ArtistInspector(o)

Bases: object

A helper class to inspect an Artist and return information about it’s settable properties and their current values.

Initialize the artist inspector with an Artist or sequence of Artists. If a sequence is used, we assume it is a homogeneous sequence (all Artists are of the same type) and it is your responsibility to make sure this is so.

aliased_name(s)

return ‘PROPNAME or alias’ if s has an alias, else return PROPNAME.

e.g., for the line markerfacecolor property, which has an alias, return ‘markerfacecolor or mfc’ and for the transform property, which does not, return ‘transform’

aliased_name_rest(s, target)

return ‘PROPNAME or alias’ if s has an alias, else return PROPNAME formatted for ReST

e.g., for the line markerfacecolor property, which has an alias, return ‘markerfacecolor or mfc’ and for the transform property, which does not, return ‘transform’

findobj(match=None)

Recursively find all matplotlib.artist.Artist instances contained in self.

If match is not None, it can be

• function with signature boolean = match(artist)
• class instance: e.g., Line2D

used to filter matches.

get_aliases()

Get a dict mapping fullname -> alias for each alias in the ArtistInspector.

e.g., for lines:

{'markerfacecolor': 'mfc',
 'linewidth'      : 'lw',
}

get_setters()

Get the attribute strings with setters for object. e.g., for a line, return ['markerfacecolor', 'linewidth', ....].

get_valid_values(attr)

Get the legal arguments for the setter associated with attr.

This is done by querying the docstring of the function set_attr for a line that begins with ACCEPTS:

e.g., for a line linestyle, return “[ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]”

is_alias(o)

Return True if method object o is an alias for another function.

pprint_getters()

Return the getters and actual values as list of strings.

pprint_setters(prop=None, leadingspace=2)

If prop is None, return a list of strings of all settable properies and their valid values.

If prop is not None, it is a valid property name and that property will be returned as a string of property : valid values.

pprint_setters_rest(prop=None, leadingspace=2)

If prop is None, return a list of strings of all settable properies and their valid values. Format the output for ReST

If prop is not None, it is a valid property name and that property will be returned as a string of property : valid values.

properties()

return a dictionary mapping property name -> value

matplotlib.artist.allow_rasterization(draw)

Decorator for Artist.draw method. Provides routines that run before and after the draw call. The before and after functions are useful for changing artist-dependant renderer attributes or making other setup function calls, such as starting and flushing a mixed-mode renderer.

matplotlib.artist.get(obj, property=None)

Return the value of object’s property. property is an optional string for the property you want to return

Example usage:

getp(obj)  # get all the object properties
getp(obj, 'linestyle')  # get the linestyle property

obj is a Artist instance, e.g., Line2D or an instance of a Axes or matplotlib.text.Text. If the property is ‘somename’, this function returns

obj.get_somename()

getp() can be used to query all the gettable properties with getp(obj). Many properties have aliases for shorter typing, e.g. ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names will be listed as:

property or alias = value

e.g.:

linewidth or lw = 2

matplotlib.artist.getp(obj, property=None)

Return the value of object’s property. property is an optional string for the property you want to return

Example usage:

getp(obj)  # get all the object properties
getp(obj, 'linestyle')  # get the linestyle property

obj is a Artist instance, e.g., Line2D or an instance of a Axes or matplotlib.text.Text. If the property is ‘somename’, this function returns

obj.get_somename()

getp() can be used to query all the gettable properties with getp(obj). Many properties have aliases for shorter typing, e.g. ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names will be listed as:

property or alias = value

e.g.:

linewidth or lw = 2

matplotlib.artist.kwdoc(a)

matplotlib.artist.setp(obj, *args, **kwargs)

Set a property on an artist object.

matplotlib supports the use of setp() (“set property”) and getp() to set and get object properties, as well as to do introspection on the object. For example, to set the linestyle of a line to be dashed, you can do:

>>> line, = plot([1,2,3])
>>> setp(line, linestyle='--')

If you want to know the valid types of arguments, you can provide the name of the property you want to set without a value:

>>> setp(line, 'linestyle')
    linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]

If you want to see all the properties that can be set, and their possible values, you can do:

>>> setp(line)
    ... long output listing omitted

setp() operates on a single instance or a list of instances. If you are in query mode introspecting the possible values, only the first instance in the sequence is used. When actually setting values, all the instances will be set. e.g., suppose you have a list of two lines, the following will make both lines thicker and red:

>>> x = arange(0,1.0,0.01)
>>> y1 = sin(2*pi*x)
>>> y2 = sin(4*pi*x)
>>> lines = plot(x, y1, x, y2)
>>> setp(lines, linewidth=2, color='r')

setp() works with the MATLAB style string/value pairs or with python kwargs. For example, the following are equivalent:

>>> setp(lines, 'linewidth', 2, 'color', 'r')  # MATLAB style
>>> setp(lines, linewidth=2, color='r')        # python style