.. contents:: Table of Contents

.. author:: Michiel de Hoon

.. date:: July 11, 2015

Discussion

None so far.

To set the transparency (alpha component) of a graphics context, eithergc.set_alpha(alpha) orgc.set_foreground(rgba, isRGBA=True) can be used. Currently,gc.set_alpha(alpha) forces the alpha value, meaning thatgc.set_foreground(rgba, isRGBA=True) will ignore the alpha value of rgba if alpha was previously set throughgc.set_alpha. Forcing alpha adds complexity toGraphicsContextBase as well as to the Cairo and MacOSX backends, in which this behavior is partially implemented.

In GraphicsContextBase,set_alpha is defined as follows:

defset_alpha(self,alpha):"""        Set the alpha value used for blending - not supported on all backends.        If ``alpha=None`` (the default), the alpha components of the        foreground and fill colors will be used to set their respective        transparencies (where applicable); otherwise, ``alpha`` will override        them.        """

whileset_foreground is defined as

defset_foreground(self,fg,isRGBA=False):"""        Set the foreground color.  fg can be a MATLAB format string, a        html hex color string, an rgb or rgba unit tuple, or a float between 0        and 1.  In the latter case, grayscale is used.        If you know fg is rgba, set ``isRGBA=True`` for efficiency.        """

As a concrete example,

a=0.7rgba= (1,0,0,0.5)# red, 50% transparentgc.set_alpha(a)gc.set_foreground(rgba,isRGBA=True)

results in an alpha value of 0.7 being used; the 0.5 in rgba is ignored. While this is a trivial example, in cases wheregc.set_alpha andgc.set_foreground appear in distant parts of the code (e.g. in different functions) it may not be obvious to the programmer that the alpha component of rgba is ignored.

Note that if in a particular case the programmer wantsgc.set_alpha to override the alpha component in rgba, then simply passing the first three components of rgba will achieve the desired effect:

gc.set_alpha(a)gc.set_foreground(rgba[:3],isRGBA=True)

results in an alpha value of 0.7 being used.

Calls togc.set_alpha are made in:

• In lib/matplotlib/image.py, in thedraw methods of_AxesImageBase,PcolorImage,FigureImage, andBboxImage;
• In lib/matplotlib/lines.py, in thedraw method ofLine2D (five calls total);
• In lib/matplotlib/patches.py, in thedraw methods ofPatch andFancyArrowPatch;
• In lib/matplotlib/patheffects.py, in thedraw_path methods ofSimplePatchShadow andSimpleLineShadow;
• In lib/matplotlib/text.py, in thedraw method ofText;
• In lib/mpl_toolkits/axisartist/axis_artist.py, in thedraw method ofBezierPath andTicks.

Note that these do not necessarily rely on the fact thatgc.set_alpha(alpha) overridesgc.set_foreground(rgba); this remains to be verified.

• Review the current usage ofgc.set_alpha and make the required changes, if any;
• Remove the_forced_alpha sections from GraphicsContextBase, RendererCairo, GraphicsContextCairo, RendererMac, GraphicsContextMac, and _macosx.GraphicsContext.

The proposal changes the usage of the graphics context only. Since the graphics context is part of the internal API of matplotlib, this proposal is not expected to affect end users.