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.
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
boolean = match(artist)
used to filter matchesIf 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_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_path_effects()
get_picker()
Return the picker object used by this artist
get_rasterized()
return True if the artist is to be rasterized
get_sketch_params()
Returns the sketch parameters for the artist.
Returns: |
sketch_params : tuple or A 3-tuple with the following elements:
May return |
---|
get_snap()
Returns the snap setting which may be:
Only supported by the Agg and MacOSX backends.
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.
mouseover
pchanged()
Fire an event when property changed, calling all of the registered callbacks.
pick(mouseevent)
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()
set(**kwargs)
A property batch setter. Pass kwargs to set properties. Will handle property name collisions (e.g., if both ‘color’ and ‘facecolor’ are specified, the property with higher priority gets set last).
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_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:
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.
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.
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_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:
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_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 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:
Only supported by the Agg and MacOSX backends.
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.
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
boolean = match(artist)
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
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:
e.g.:
linewidth or lw = 2matplotlib.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
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:
e.g.:
linewidth or lw = 2matplotlib.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
© 2012–2016 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
http://matplotlib.org/1.5.3/api/artist_api.html